Registre eventos do usuário em tempo real

Nesta página, você verá como registrar eventos do usuário em tempo real. A Vertex AI para Pesquisa para varejo usa eventos de usuário em tempo real para gerar recomendações e resultados de pesquisa. Gravar o maior número possível de eventos do usuário com informações válidas do produto aumenta a qualidade dos resultados.

Os procedimentos de gravação nesta página se aplicam às recomendações e à pesquisa. Depois que você gravar dados, os dois serviços poderão usar esses eventos. Portanto, não será necessário fazer o upload dos mesmos dados duas vezes se você usar os dois serviços.

Para detalhes sobre eventos do usuário, incluindo tipos de evento do usuário e JSON de amostra para todos os tipos, consulte Sobre os eventos do usuário.

Você pode registrar um evento de usuário de várias maneiras:

Veja abaixo exemplos de como registrar eventos do usuário do tipo detail-page-view para todos esses métodos. Para outros tipos de evento, consulte Sobre os eventos do usuário.

Também é possível importar eventos históricos do usuário. Pode levar um tempo considerável para registrar dados suficientes de eventos do usuário para treinar seus modelos. É possível acelerar o treinamento inicial do modelo importando dados de eventos do usuário de eventos anteriores em massa. Consulte Importar eventos históricos do usuário.

Se o evento do usuário que você está gravando for a primeira vez que um usuário interage com um produto com base em uma recomendação ou nos resultados da pesquisa fornecidos anteriormente, incluindo um token de atribuição permitirá que a API Retail forneça métricas de desempenho. É necessário incluir um token de atribuição para que a Vertex AI para Pesquisa para varejo funcione. Para informações sobre como trabalhar com tokens de atribuição, consulte Tokens de atribuição.

Os IDs de visitantes são necessários para gravar eventos do usuário. Para informações sobre IDs de visitante e de usuário, consulte Sobre as informações do usuário.

Gravar eventos do usuário com a inclusão de tags no servidor

A inclusão de tags no servidor permite implantar um único contêiner no servidor com muitos clientes downstream. Isso cria uma única fonte de verdade no lado do cliente, com muitos consumidores do lado do servidor. Essa arquitetura transfere a carga da Web para o servidor, tornando-a desejável para usuários que querem maximizar o desempenho dos sites.

Outra vantagem da inclusão de tags no servidor é que uma única tag no servidor também pode oferecer suporte a muitos clientes upstream, por exemplo, à Web e a dispositivos móveis. Saiba como configurar a inclusão de tags no servidor.

A Vertex AI para Pesquisa para varejo oferece a própria tag nativa do lado do servidor.

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

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

A principal diferença entre a versão do servidor e a versão da Web da tag do Cloud Retail é que você não pode definir a origem dos dados. A origem de dados para tags do servidor é um fluxo de dados enviado pela tag do Google no esquema do GA4.

Configurar a tag do Cloud Retail

Tutorial para criar eventos de usuário

Este tutorial mostra como gravar eventos do usuário usando o método userEvents.write.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Antes de começar

Antes de gravar eventos do usuário, faça o seguinte:

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

  • uma chave de API válida (para o Pixel ou JavaScript do Gerenciador de tags) ou uma conta de serviço válida com o papel de editor de varejo atribuído, caso seja usada para gravar diretamente.

    Para mais informações, consulte Antes de começar.

Práticas recomendadas para registrar eventos do usuário

A Vertex AI para Pesquisa de varejo requer dados de alta qualidade para gerar resultados de alta qualidade. Se os dados estiverem incompletos ou incorretos, a qualidade dos resultados será prejudicada.

Ao registrar eventos do usuário, implemente as seguintes práticas recomendadas:

  • Se você gravar eventos do usuário antes ou durante a importação do seu catálogo, reconecte-se a qualquer evento registrado antes da conclusão da importação do catálogo.

    É possível importar o catálogo antes, depois ou ao mesmo tempo em que você registra eventos do usuário. Essas tarefas em paralelo podem economizar tempo se o catálogo for grande e houver muitos eventos de usuários. Quando a importação do catálogo estiver concluída, você precisará usar a API para reunir os eventos que foram enviados antes da conclusão da importação.

    A Vertex AI Search para varejo tenta mesclar eventos do usuário registrados com metadados do catálogo de produtos quando o evento do usuário é criado. Somente os eventos mesclados são usados para o treinamento. Portanto, reconecte os eventos gravados antes da importação completa do catálogo. Se um evento se referir a um item que não existe no catálogo, ele será descartado ou não associado aos produtos corretos. Da mesma forma, se você importar eventos de usuários no passado, o catálogo precisará incluir todos os produtos aos quais eles fazem referência. você pode marcar produtos mais antigos como OUT_OF_STOCK em vez de removê-los do catálogo.

  • Mantenha seu catálogo atualizado.

    Quando você registra eventos do usuário, o produto incluído no evento do usuário é conectado ao seu catálogo atual. Se você registrar um evento para um produto que não está no catálogo atual, ele não poderá ser usado para treinar seus modelos. Isso é chamado de evento "unjoined". Se você gravou eventos antes da importação completa do seu catálogo, será necessário reingressar nos eventos que foram gravados durante a importação. Espera-se que alguns eventos não sejam agrupados. No entanto, se a porcentagem de eventos não associados atingir 5% ou mais do total de eventos do usuário, verifique se o catálogo está atualizado, refaça os eventos que foram gravados antes da atualização completa do catálogo e investigue por que os eventos não associados estão sendo criados.

    É possível ver os eventos não associados usando a filtragem de eventos. Saiba mais.

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

    Cada tipo de evento do usuário tem informações diferentes que são obrigatórias e aceitas. Para mais informações, consulte Sobre os eventos do usuário.

  • Configure alertas do Cloud Monitoring para saber se os processos de gravação de eventos do usuário sofreram interrupções.

  • Para uma importação de eventos em massa de usuários, limite o tamanho dos dados que você está importando.

    A importação de eventos em massa de usuários pode levar até 24 horas para ser concluída.

    O tamanho de cada arquivo precisa ser de 2 GB ou menor. É possível incluir no máximo 100 arquivos em uma única solicitação de importação. Uma delas é importar somente os eventos de usuários um dia de cada vez.

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

  • Ao importar dados do evento do usuário, inclua um carimbo de data/hora preciso para cada evento e evite importar eventos sequenciais do usuário com carimbos de data/hora idênticos.

    Forneça o carimbo de data/hora no campo eventTime no formato especificado pelo RFC 3339.

  • Se você importou eventos de usuário incorretos, fale com seu contato da Pesquisa da Vertex AI para varejo sobre como corrigir o problema.

  • Quando possível, mantenha os dados do evento do usuário contínuos.

    Lacunas nos dados de eventos do usuário podem reduzir a qualidade do modelo.

  • Use uma forma segura de um identificador exclusivo para manter os usuários anônimos na Pesquisa da Vertex AI para varejo e proteger a privacidade deles. Você é responsável por editar PII (informações de identificação pessoal), como e-mails ou endereços residenciais, dos seus dados.

Gravar eventos do usuário com um pixel JavaScript

O exemplo a seguir registra um UserEvent de detail-page-view usando um pixel JavaScript.

<script type="text/javascript">
var user_event = {
  "eventType" : "detail-page-view",
  "visitorId": "visitor-id",
  "userInfo": {
      "userId": "user-id"
  },
  "attributionToken": "attribution-token",
  "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 você importou eventos do usuário com o Google Analytics 360, defina visitorID como o ID do cliente do Google Analytics. O ID do cliente do Google Analytics faz parte apenas do nome completo do cookie _ga. Por exemplo, o ID do cliente 123456789.123456789 faz parte do cookie _ga GA1.3.123456789.123456789.

Veja a seguir um exemplo abreviado que mostra o formato para definir o ID do cliente em um evento do usuário. 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>

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

É 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.

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

Registrar eventos do usuário com o Google Analytics 4

Você pode registrar dados de eventos do usuário do Google Analytics 4 na Vertex AI para Pesquisa para varejo.

Verificar a fonte de dados

Verifique se os dados de eventos do usuário que você quer importar estão formatados corretamente.

Para conferir uma tabela de campos do Google Analytics 4 que a Vertex AI para Pesquisa para varejo usa e para quais campos da Vertex AI para Pesquisa para varejo eles são mapeados, consulte Campos de eventos do usuário do Google Analytics 4.

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

Verifique se:

  1. Se você estiver importando eventos de compra, que alguns modelos da Vertex AI para Pesquisa de varejo exigem, os relatórios de eventos vão incluir códigos de moeda. Consulte os parâmetros de evento purchase na documentação do Google Analytics.

  2. Se você pretende importar eventos search, o relatório de eventos vai incluir consultas de pesquisa.

    A importação de eventos search é compatível, mas eles não são mapeados do Google Analytics 4 da mesma forma que outros tipos de eventos, porque o Google Analytics 4 não é compatível nativamente com o tipo de evento search da Pesquisa da Vertex AI para varejo.search Durante a importação, os eventos search são criados no Google Analytics 4 combinando informações dos parâmetros de evento view_item_list e search_term.

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

Registrar seus eventos do Google Analytics 4

Grave um evento do usuário incluindo dados JSON brutos codificados por URL para o evento na chamada para o método userEvents.collect.

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

Para facilitar a leitura, o exemplo a seguir de uso da chamada userEvents.collect define primeiro GA4_EVENT como uma variável que contém os dados JSON brutos de um exemplo de evento. A chamada userEvents.collect no exemplo codifica os dados do evento usando o URL e a variável GA4_EVENT.

  1. Para facilitar a codificação de URL mais tarde, defina GA4_EVENT como uma variável que contém dados do evento. 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 brutos codificados em URL de um evento do usuário:

    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'"

Gravar eventos do usuário com o Gerenciador de tags do Google

O Gerenciador de tags oferece uma maneira de gerenciar e testar várias tags sem muitas alterações de código no servidor para seu site.

Algumas decisões que você toma durante a configuração dependem do uso do Google Analytics e do Google Analytics Comércio Eletrônico. O e-commerce do Google Analytics pode ser implementado usando o Google Analytics 4 ou o e-commerce avançado. A tag do Cloud Retail é compatível com os dois.

Nem o Google Analytics nem o Google Analytics para e-commerce são obrigatórios. Se você não os usa, pode configurar Variável: e-commerce ao criar a tag do Cloud Retail ou preencher manualmente o código da camada de dados do site após a criação da tag.

O e-commerce do Google Analytics é uma configuração adicional para o Google Analytics que transmite títulos de produtos, IDs, preços, detalhes de transações e outros dados de e-commerce estruturados para o Google Analytics. A Vertex AI Search para varejo pode usar automaticamente a camada de dados de comércio eletrônico do Google Analytics. Portanto, se você já tiver configurado esse recurso, a configuração poderá ser mais fácil. Se você não tiver o e-commerce do Google Analytics configurado para o Google Analytics, mas quiser usá-lo, consulte mais detalhes e instruções de configuração no Guia do desenvolvedor do GA4.

Use este procedimento único para configurar uma tag do Cloud Retail no Gerenciador de tags e registrar eventos do usuário.

Criar uma variável de ID de visitante

O valor visitorId é para rastrear usuários. visitorId normalmente é um ID de sessão e é necessário para todos os eventos. Configure uma variável que defina códigos de sessão como visitorId.

Se você estiver usando o Google Analytics, poderá utilizar o ID de visitante da plataforma. Para configurar isso, use o procedimento a seguir para substituir o valor do ID de visitante da tag do Cloud Retail. Isso mapeia o cookie primário "_ga" para uma variável do Gerenciador de tags chamada "Visitas da conta do GA". É possível fazer o mesmo para qualquer cookie de ID de sessão. não precisa ser do Google Analytics.

Para este procedimento, pressupomos que você esteja usando o Google Analytics. Se não estiver, use outro cookie ou variável ou consiga o ID do visitante na camada de dados cloud_retail.

Para definir o valor visitorID como uma variável da tag do Cloud Retail:

  1. No Gerenciador de tags, acesse a guia Variáveis e clique em Nova para criar uma nova variável definida pelo usuário.

  2. Dê um nome à variável na parte superior da caixa de diálogo, como "ID do visitante do GA".

  3. Insira as configurações da variável.

    É possível usar o ID do cliente ou do cookie para definir a origem dos IDs de visitante. Sempre use uma origem de ID de visitante consistente ao ingerir eventos históricos e em tempo real do usuário.

    ID do cliente

    No Google Analytics 4, essa variável é mapeada para o campo user_pseudo_id no esquema de exportação do BigQuery do Google Analytics 4.

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

    2. Digite o script a seguir no campo JavaScript personalizado.

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

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

    3. Clique em Salvar para salvar a variável.

    1. Escolha Cookie primário como o tipo de variável.

    2. No campo Nome do cookie, digite _ga.

    3. Clique em Valor do formato, selecione Converter indefinido para.. e insira "" (uma string vazia).

    4. Clique em Salvar para salvar a variável.

      Isso mapeia o cookie primário "_ga" para uma variável do Gerenciador de tags chamada "visitante da conta do GA".

Em seguida, crie uma tag do Cloud Retail no Gerenciador de tags. Essa tag usará a variável de ID do visitante que você acabou de criar.

Criar uma tag do Gerenciador de tags do Google

Configure uma tag no Gerenciador de tags para enviar informações do evento do usuário à Vertex AI Search for Retail.

  1. Faça login no Gerenciador de tags e selecione o contêiner do seu site.

  2. Acesse a guia Tags e clique em Nova para adicionar uma nova tag.

  3. Dê um nome à tag na parte de cima do painel (o marcador é Variável sem título), como "Pesquisa da Vertex AI para varejo".

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

  5. Insira sua chave de API.

    Use a chave que você criou ao configurar a Vertex AI para Pesquisa para varejo.

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

  6. Insira o número do projeto do Google Cloud em que a pesquisa da Vertex AI para varejo está ativada.

    O número do projeto está disponível no painel do console do Google Cloud.

  7. No campo Fonte de dados de eventos do usuário:

    • Camada de dados (recomendada): selecione se a implementação será uma das seguintes:

      • Você implementou o e-commerce do Google Analytics pelo Gerenciador de tags. Reutilize a camada de dados como sua fonte de dados de eventos, em vez de preencher uma nova. Isso usa o esquema do Google Analytics 4, se presente. Caso contrário, ele usa o e-commerce avançado do UA. Com essa fonte de dados, só é possível gravar eventos add-to-cart, purchase-complete, detail-page-view e search. Os eventos search são registrados usando impressões de e-commerce combinadas com consultas de pesquisa. Consulte Criar uma variável de consulta de pesquisa.

      • Você está usando o e-commerce do Google Analytics e pode preencher manualmente o código da camada de dados. Consulte o Guia para desenvolvedores do Gerenciador de tags.

    • Variável: Cloud Retail: selecione para preencher uma variável do Gerenciador de tags com os campos obrigatórios da Vertex AI para Pesquisa para varejo. É possível escolher essa opção se você não estiver usando o comércio eletrônico do Google Analytics ou se ele não tiver os dados necessários para a pesquisa da Vertex AI para varejo. Se você estiver mudando para essa origem da opção legada da camada de dados - Cloud Retail, crie também uma variável da camada de dados com a chave cloud_retail e a associe a essa opção Variável - Cloud Retail.

    • Variável: comércio eletrônico: selecione se você não estiver usando o comércio eletrônico do Google Analytics na camada de dados e não puder preencher manualmente o código da camada de dados.

      No campo Ler dados de comércio eletrônico da variável de usuário exibido, escolha uma variável. Isso permite que a Pesquisa Vertex AI para varejo leia dados de eventos do usuário de e-commerce do Google Analytics de uma variável personalizada criada por você.

      A variável precisa corresponder ao formato documentado no Guia para desenvolvedores do GA4. Para criar uma variável no formato correto, use o Criador de objetos de comércio eletrônico avançado, um modelo de variável personalizada da Tag Galeria de modelos da comunidade de administradores Os modelos da comunidade não são mantidos pelo Google. Para usar esse modelo, consulte a página da galeria do Criador de objetos de comércio eletrônico avançado para conferir a documentação e outros recursos.

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

  9. Em Seletor de campo, selecione visitorId como o campo. Em Valor do campo, selecione a nova variável de ID de visitante que você criou em Criar uma variável de ID de visitante.

  10. Clique em Salvar.

    Sua tag do Cloud Retail foi criada.

Opções de origem de dados legadas

Antes, a Camada de dados: e-commerce e a Camada de dados: Cloud Retail estavam disponíveis como opções de fonte de dados. Essas opções legadas não estão disponíveis em novas tags. Se você mudar uma tag para uma nova fonte de dados, faça uma prévia dela com o Gerenciador de tags para verificar antes da implantação. Ao mudar:

  • Se você usou a Camada de dados: e-commerce, mude para a Camada de dados. Isso usa o esquema do Google Analytics 4, se presente. Caso contrário, ele usa o e-commerce avançado do UA.

  • Se você usou a 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.

Próximo:

Criar uma variável de consulta de pesquisa

Se você estiver usando a pesquisa, crie uma variável no Gerenciador de tags para consultas de pesquisa e anexe-a à tag do Cloud Retail. Isso permite que a Vertex AI para Pesquisa para varejo receba consultas de pesquisa do Google Analytics.

Os tipos de variáveis criadas dependem da origem de dados de eventos do usuário.

  • Variável: e-commerce ou a camada de dados com o esquema de e-commerce do Google Analytics: crie uma variável de elemento de URL ou DOM no Gerenciador de tags e anexe-a à tag do Cloud Retail. Além disso, ative a opção para que sua tag use impressões de e-commerce do Google Analytics para criar eventos de pesquisa.
  • Variável: Cloud Retail ou uma camada de dados preenchida manualmente: crie uma variável de elemento de URL ou DOM no Gerenciador de tags e anexe-a à tag do Cloud Retail. Para determinar se o tipo de um evento do usuário é search, você também precisa:
    • Crie uma variável de tipo constante para os tipos de evento de pesquisa e anexe-a à tag.
    • Defina o tipo de evento de pesquisa na camada de dados ou na variável do Cloud Retail.

Criar e anexar uma variável do Gerenciador de tags para consultas de pesquisa

Se você usa a pesquisa, pode criar um URL, um elemento DOM ou uma variável JavaScript personalizada que será preenchida com consultas de pesquisa inseridas no site.

Como alternativa a esse procedimento, é possível configurar a camada de dados para fornecer informações de consulta de pesquisa. No entanto, você pode optar por usar as variáveis do Gerenciador de tags se não tiver acesso à camada de dados ou preferir não configurá-la.

Você pode criar uma variável de tipo de URL, uma variável de tipo de elemento DOM ou uma variável JavaScript (página) personalizada. A criação e a configuração dependem da implementação do site:

  • Uma variável de URL recebe consultas de pesquisa dos URLs de resultado da pesquisa do seu site. Use essa variável se o site incluir a string de consulta no URL dos resultados da pesquisa.
  • Uma variável Elemento DOM recebe as informações da consulta de pesquisa do Modelo de Objeto de Documento (DOM, na sigla em inglês) do seu site. Não é necessário editar o DOM para usar essa variável. No entanto, você será capaz de ler e entender o DOM para configurar essa variável corretamente.
  • Uma variável JavaScript personalizada retorna dados formatados por uma função JavaScript. Isso é útil se você tiver dados que quer formatar no esquema de varejo ou e-commerce do Cloud.

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

  1. No Gerenciador de tags, acesse a guia Variáveis e clique em Nova para criar uma nova variável definida pelo usuário.

  2. Dê um nome à variável na parte superior da caixa de diálogo, como "variável_de_pesquisa".

  3. Insira as configurações da variável:

    Tipo de URL

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

    2. Defina Tipo de componente como Consulta.

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

      Por exemplo, se o URL for http://example.com/?q=shoes, a chave de consulta será 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 insira o seletor de ID ou elemento do elemento da consulta de pesquisa.

      Essa configuração depende do site usar um código de elemento ou um seletor de CSS para identificar a consulta de pesquisa.

    3. Se você 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 será value. Nesse 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 abaixo e cole no painel "JavaScript personalizado".

    3. No painel "JavaScript personalizado", adicione um código JavaScript que retorne um evento de pesquisa no Esquema de varejo.

      O código de exemplo a seguir transforma os dados em uma variável Ecommerce Items existente no array productDetails usado pela Pesquisa da Vertex AI para o esquema de varejo e retorna um evento completo. Para usar esse código, substitua Ecommerce Items, Search Query e Search Filter por variáveis na implementação do Gerenciador de tags.

      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 Salvar para salvar a variável.

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

  1. Na página Tags, do Gerenciador de tags, clique na sua tag do Cloud Retail para editá-la.

  2. Se a origem de dados do evento do usuário da tag for Variável: e-commerce ou se você usar a camada de dados com o esquema de e-commerce do Google Analytics, marque a caixa de seleção Usar impressões de e-commerce avançado para criar eventos de pesquisa.

    Isso permite que a Vertex AI para Pesquisa para varejo determine se o tipo de evento de um usuário é search com base nos dados de pesquisa dessa tag.

  3. Na seção Dados de eventos do usuário, clique no botão + Substituir um valor na mensagem do UserEvent.

  4. Selecione searchQuery em Seletor de campo e defina sua variável de consulta de pesquisa como o Valor do campo.

  5. Salve sua tag.

Próximo:

Criar e anexar uma variável constante

Use este procedimento se você escolheu Variável: Cloud Retail ou uma camada de dados preenchida manualmente como a origem do evento do usuário para sua tag do Cloud Retail.

Criar uma variável de tipo constante para eventos de pesquisa e defini-la como uma substituição de evento de usuário na tag do Cloud Retail permite que a Pesquisa de varejo da Vertex AI determine se o tipo de evento de um usuário é search.

Como alternativa a esse procedimento, é possível especificar o tipo de evento de usuário search por meio da camada de dados ou da variável do Cloud Retail que você está usando como origem de eventos da tag. Caso contrário, siga as etapas abaixo para definir o tipo de evento.

Primeiro, crie uma variável de tipo constante:

  1. No Gerenciador de tags, acesse a guia Variáveis e clique em Nova para criar uma nova variável definida pelo usuário.

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

  3. Defina Tipo de variável como Constante.

  4. Insira search no campo Valor.

  5. Clique em Salvar para salvar a variável.

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

  1. Na página Tags, do Gerenciador de tags, clique na sua tag do Cloud Retail para editá-la.

  2. Na seção Dados de eventos do usuário, clique no botão + Substituir um valor na mensagem do UserEvent.

  3. Selecione eventType em Seletor de campo e defina sua variável de consulta de pesquisa como o Valor do campo.

  4. Salve sua tag.

Em seguida, crie acionadores de eventos para sua tag.

Criar acionadores de eventos para sua tag do Gerenciador de tags

Crie acionadores para todos os tipos de evento de usuário que seus modelos de varejo da Vertex AI para Pesquisa vão usar.

As tags do Gerenciador de tags precisam ter acionadores que controlam quando a tag deve ser "disparada" no site. Os acionadores detectam quando os eventos ocorrem (como quando um usuário visualiza a página inicial ou adiciona um item ao carrinho) e solicita que a tag envie essas informações de evento do usuário para a Pesquisa da Vertex AI para varejo.

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

Geralmente, a tag é acionada quando um usuário visualiza qualquer página que tenha os eventos necessários para a Vertex AI Search para varejo, como a página inicial, as páginas de detalhes do produto, as páginas do carrinho ou a página de finalização da compra. Nesses casos, a tag precisa ser disparada após o carregamento da página. Assim, os cookies estarão disponíveis e todas as variáveis da camada de dados serão preenchidas. Para fazer isso, defina os acionadores que serão disparados em Window Loaded ou DOM Ready.

Talvez seja necessário disparar a tag quando uma ação for realizada, em vez de fazer isso no carregamento de página. Por exemplo, se um usuário que adiciona um item a um carrinho não forçar a atualização da página. Nesses casos, você pode configurar essa ação de clique no seu site para enviar atualizações simultaneamente para a camada de dados e associar o gatilho a essa ação.

Por exemplo, se você criou um gatilho para eventos add-to-cart, poderá escolher o tipo de gatilho para Clique - Apenas links e defini-lo para disparar no ID de clique (em neste exemplo, addtocart). Em seguida, você configuraria o link addtocart no seu site para também atualizar a camada de dados com novos valores quando 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 usuário, você precisa criar um acionador personalizado. Geralmente, você cria um acionador personalizado no Gerenciador de tags usando o nome do evento. Se não for possível modificar o código do front-end, você poderá criar um gatilho personalizado usando macros JavaScript. Para mais informações sobre gatilhos personalizados, consulte Gatilho de evento personalizado.

Use os seguintes procedimentos para criar acionadores no Gerenciador de tags:

Criar novos acionadores para sua tag do Gerenciador de tags

Se você não usa o e-commerce do Google Analytics, crie novos acionadores de eventos para os eventos de usuário que seus modelos de varejo da Vertex AI para Pesquisa precisam. Em seguida, associe os novos acionadores à tag do Cloud Retail criada no Gerenciador de tags.

Antes de iniciar as próximas etapas, verifique se você criou uma tag do Cloud Retail no Gerenciador de tags. Consulte Criar uma tag do Gerenciador de tags.

Primeiro, crie os acionadores. Repita este procedimento para todos os eventos de usuário que seus modelos da Vertex AI Search para varejo exigem:

  1. Na página Gerenciador de tags, em Acionadores, clique em Novo > Configuração de acionador.

  2. Escolha o tipo de gatilho que se aplica ao evento de usuário para o qual você está criando um gatilho.

  3. Salve o gatilho.

Em seguida, associe os novos acionadores à sua tag do Cloud Retail. Esse é um procedimento único:

  1. Na página Tags, do Gerenciador de tags, clique na sua tag do Cloud Retail para editá-la.

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

  3. Salve sua tag.

Em seguida, visualize sua tag e configure o monitoramento de erros de gravação de eventos e outros problemas para garantir que os dados continuem sendo recebidos.

Se você estiver usando a camada de dados cloud_retail como fonte de evento do usuário, configure sua camada de dados.

Reutilizar acionadores de e-commerce do Google Analytics

Se você tiver implementado o e-commerce do Google Analytics pelo Gerenciador de tags, reutilize os acionadores de eventos do e-commerce do Google Analytics para a Pesquisa Vertex AI para varejo.

Com essa fonte de dados, só é possível gravar eventos add-to-cart, purchase-complete, detail-page-view e search. Os eventos search são registrados usando impressões de e-commerce combinadas com consultas de pesquisa. Consulte Criar uma variável de consulta de pesquisa.

A tabela a seguir mostra como os eventos de e-commerce e de e-commerce avançado do Google Analytics são mapeados para a Pesquisa da Vertex AI para eventos de varejo.

Google Analytics 4 E-commerce avançado Vertex AI para Pesquisa para varejo
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 estas etapas, confirme se você:

  • Configure uma tag no Gerenciador de tags do tipo Google Analytics: evento do GA4 e ative o comércio eletrônico avançado ou o GA4 nela. Consulte a documentação do Gerenciador de tags e o Guia para desenvolvedores do GA4 para saber mais.
  • Configure a tag do comércio eletrônico avançado ou do GA4 no Gerenciador de tags para acionar os eventos de usuário que você pretende registrar na Pesquisa da Vertex AI para varejo.
  • Uma tag do Cloud Retail foi criada no Gerenciador de tags com a "Camada de dados" ou a "Variável: comércio eletrônico" como a origem de dados do evento do usuário. Consulte Criar uma tag do Gerenciador de tags.

Para reutilizar os acionadores de e-commerce do Google Analytics:

  1. Na página Tags do Gerenciador de tags, clique na tag de e-commerce do Google Analytics (tipo Google Analytics: evento do GA4) para editá-la.

  2. Em Configurações avançadas > Sequenciamento de tags, selecione Acionar uma tag depois do disparo de <nome da tag de comércio eletrônico avançado ou do GA4>.

  3. Selecione sua tag do Cloud Retail como Tag de limpeza.

    Selecione Não disparar <nome da tag do Cloud Retail> se <nome da tag de comércio eletrônico avançado ou do GA4> falhar ou estiver pausada.

  4. Salve sua tag.

Em seguida, visualize sua tag e configure o monitoramento de erros de gravação de eventos e outros problemas para garantir que os dados continuem sendo recebidos.

Se você estiver usando a camada de dados cloud_retail como fonte de evento do usuário, configure sua camada de dados.

Usar a camada de dados cloud_retail com o Gerenciador de tags

Se você criou sua tag do Cloud Retail no Gerenciador de tags para usar a camada de dados cloud_retail como origem do evento do usuário, configure a variável dataLayer no HTML de origem, conforme descrito na Guia do desenvolvedor do Gerenciador de tags.

Sobre a camada de dados

A maioria das tags do Gerenciador de tags requer dados que mudam dependendo do usuário ou da página (como IDs de usuário ou de produto). No caso da tag do Cloud Retail, esses dados precisam ser expostos de maneira estruturada por meio de uma camada de dados para que o Gerenciador de tags possa usá-los.

A camada de dados é um objeto JavaScript que normalmente é adicionado a uma página com código do lado do servidor ou no front-end usando HTML ou um modelo. Se uma página for configurada com a camada de dados, ela conterá um código como este:

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

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

Esse código cria um objeto dataLayer e atribui a estrutura cloud_retail a ele como um elemento de matriz.

Campos obrigatórios na camada de dados cloud_retail

A seção Sobre os eventos do usuário lista todos os campos e exemplos obrigatórios de tipos de evento que precisam ser transmitidos à camada de dados cloud_retail.

Seu código ou modelos do servidor precisam ter as tags de script corretas em cada página de que você quer enviar eventos. Depois que o objeto dataLayer for preenchido corretamente em cada página, teste a tag do Cloud Retail.

Alguns campos, como visitorId, são obrigatórios para a mensagem UserEvent, mas podem não estar disponíveis ao preencher a camada de dados. Por exemplo, visitorId pode ser derivado do cookie do usuário ou experimentIds do framework de experimentação A/B. Nesse caso, use uma variável para substituir o campo na tag do Gerenciador de tags.

É possível substituir os seguintes campos:

  • visitorId
  • userInfo.userId
  • attributionToken
  • experimentIds

Para saber como substituir um campo UserEvent no Gerenciador de tags, consulte Como definir o campo visitorID no Gerenciador de tags, que explica a substituição do valor do campo visitorId. com uma variável definida pelo usuário.

O exemplo a seguir mostra a camada de dados que precisa ser incluída na página para um UserEvent de detail-page-view usando o Gerenciador de tags:

<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'
      },
      'attributionToken': 'attribution-token',
      // 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>

Visualizar sua tag do Gerenciador de tags

Com o modo de visualização do Gerenciador de tags, você pode testar novas tags antes de publicá-las no seu site ativo.

Para mais detalhes sobre o modo de visualização, consulte a documentação do Gerenciador de tags do modo de visualização.

Use o procedimento a seguir para confirmar que a tag está sendo acionada corretamente.

  1. Na página de visão geral do Gerenciador de tags, clique em Visualizar.

    O modo de visualização do Gerenciador de tags é aberto em uma nova guia do navegador.

  2. Insira as informações do site e clique em Iniciar para iniciar o Assistente de tags.

    Na guia atual do navegador, o Assistente de tags é iniciado e seu site é aberto em uma nova guia.

  3. No seu site, acesse qualquer página em que a tag do Cloud Retail seja acionada.

  4. Confirme se o Assistente de tags lista a tag do Cloud Retail na guia Tags, na seção Tags disparadas.

  5. No Assistente de tags, acesse a guia Camada de dados e verifique se os valores corretos da camada de dados de comércio eletrônico ou cloud_retail são exibidos.

Verificar se há erros de tag

Se alguns campos estiverem incorretos ou ausentes ao visualizar a tag, a tag também retornará um erro, a menos que não esteja sendo disparada.

Verifique se há erros na página Monitoramento no console da Pesquisa para varejo. Esta página registra a maioria dos erros, exceto os de sintaxe, que normalmente aparecem apenas nos resultados da solicitação.

Você pode seguir as etapas abaixo para verificar se há erros gerados pelo Chrome DevTools, incluindo erros de sintaxe.

  1. Ative o modo de visualização no Gerenciador de tags para seu site em um navegador Chrome e acesse qualquer página em que a tag do Cloud Retail seja acionada.

  2. Com o modo de visualização aberto, abra o DevTools e clique na guia Network.

  3. Atualize a página.

  4. No DevTools, pesquise por userEvent.

    A guia "Rede" exibe o evento userEvent:collect e o código de status dele.

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

  5. Clique duas vezes no nome do evento para executar a solicitação e mostre uma resposta completa com mais informações de erro.

    Por exemplo, talvez você veja um erro 400 contendo a mensagem "visitorId" é obrigatória e não pode estar vazia", indicando que visitorId não foi definido corretamente.

  6. Se nenhum userEvent for disparado, verifique a guia Console do DevTools para ver erros de sintaxe na camada de dados.

Monitorar a integridade da importação

É importante gravar eventos de usuários para ter resultados de alta qualidade. Monitore as taxas de erro de gravação de eventos e tome medidas se necessário. Para mais informações, consulte Como configurar alertas para problemas de upload de dados.

Conferir eventos gravados

Confira as métricas de integração de eventos na guia Eventos da página Dados do console da Pesquisa para varejo. Esta página mostra todos os eventos gravados ou importados no último ano. As métricas podem levar até 24 horas para aparecer após a ingestão de dados.

Acessar a página "Dados"

A seguir