Registrar 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 do usuário em tempo real para gerar recomendações e resultados da 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 a recomendações e à pesquisa. Depois de registrar os dados, os dois serviços podem usar esses eventos. Assim, não é necessário fazer upload dos mesmos dados duas vezes.

Para detalhes sobre eventos do usuário, incluindo tipos de eventos do usuário e exemplos de JSON para todos os tipos, consulte Sobre eventos de 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 eventos de 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á registrando for a primeira vez que um usuário interagir com um produto com base em uma recomendação ou nos resultados da pesquisa fornecidos anteriormente, incluir um token de atribuição vai ativar as métricas de desempenho. A inclusão de um token de atribuição é opcional, mas altamente recomendada. Para informações sobre como trabalhar com tokens de atribuição, consulte Tokens de atribuição.

Os IDs dos visitantes são obrigatórios ao registrar eventos do usuário. Para informações sobre IDs de visitantes e do usuário, consulte Sobre as informações do usuário.

Tutorial para criar eventos de usuário

Neste tutorial, mostramos como registrar eventos de 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 para 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 de gravar 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 for concluída, use a API para reunir os eventos que foram enviados antes da conclusão da importação.

    A Vertex AI para Pesquisa para varejo tenta mesclar eventos de 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ê gravar 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 "não mesclado". Se você gravou eventos antes da importação do catálogo, é necessário reingressar nos eventos que foram gravados durante a importação. É esperado que haja alguns eventos desvinculados. No entanto, se a porcentagem de eventos desvinculados alcançar 5% ou mais do total de eventos de usuário, verifique se o catálogo está atualizado, reintegre os eventos gravados antes da atualização completa e investigue por que esses eventos 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. Saiba mais em Sobre os eventos de usuário.

  • Configure alertas do Cloud Monitoring para saber se os processos de gravação de eventos do usuário enfrentarem 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 deve 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 do usuário incorretos, fale com seu contato da Vertex AI para Pesquisa 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 Vertex AI para Pesquisa no 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.

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

Para mais informações sobre como conseguir o ID do cliente, consulte a documentação do Google Analytics.

Veja a seguir um exemplo abreviado que mostra o formato para definir o ID do cliente em um evento do usuário. Substitua "UA-XXXXXX-N" pelo seu ID de acompanhamento do Google Analytics.

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

Registrar 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

É possível 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 uma tabela dos campos do Google Analytics 4 que a Vertex AI para Pesquisa para varejo usa e quais campos da Vertex AI para Pesquisa para varejo são mapeados, consulte Campos de eventos do usuário 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 você estiver importando eventos de compra, que são exigidos por alguns modelos da Vertex AI para Pesquisa para varejo, seus 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ê planeja importar eventos search, seus relatórios de eventos incluem consultas de pesquisa.

    A importação de eventos search é compatível, mas os eventos search não são mapeados do Google Analytics 4 da mesma maneira que outros tipos de evento, porque o Google Analytics 4 não tem suporte nativo ao tipo de evento search da Vertex AI para Pesquisa para varejo. 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

Registre um evento do usuário incluindo dados brutos JSON codificados em 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 primeiro define GA4_EVENT como uma variável que contém os dados JSON brutos para um exemplo de evento. A chamada userEvents.collect no exemplo codifica os dados do evento em URL usando a variável GA4_EVENT.

  1. Para facilitar a codificação de URL posteriormente, defina GA4_EVENT como uma variável que contém 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 brutos JSON codificados em URL de um evento de 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'"

Registrar 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 tomadas durante a configuração dependem do uso do Google Analytics e do comércio eletrônico do Google Analytics. 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 ambos.

Os recursos de e-commerce do Google Analytics e do Google Analytics não são necessários. Se você não os usar, poderá configurar Variável – e-commerce ao criar a tag do Cloud Retail ou preencher manualmente o código da camada de dados do site depois de criar a tag.

O e-commerce do Google Analytics é uma configuração adicional do Google Analytics que transmite títulos de produtos, IDs, preços, detalhes das transações e outros dados estruturados de comércio eletrônico para o Google Analytics. A Vertex AI para Pesquisa para varejo pode usar automaticamente a camada de dados de e-commerce do Google Analytics. Portanto, se você já tem essa configuração, fica mais fácil. Se você não configurou o e-commerce do Google Analytics, mas quer usá-lo, veja mais detalhes e instruções de configuração no guia para desenvolvedores do GA4 ou no guia do desenvolvedor de e-commerce avançado.

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 do visitante

O valor visitorId serve para rastrear usuários. visitorId normalmente é um ID de sessão e é obrigató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.

    Você pode usar o ID do cliente ou do cookie para definir como a origem dos IDs de visitantes. Sempre use uma origem consistente de ID de visitante ao ingerir eventos históricos e em tempo real do usuário.

    ID do cliente

    No BigQuery do Google Analytics 360, essa variável é mapeada para o campo clientID no esquema de exportação do BigQuery do Universal Analytics. 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 "UA-XXXXXX-N" pelo seu ID de acompanhamento do Google Analytics. Para encontrar seu ID de acompanhamento, consulte O que aconteceu com meu ID de acompanhamento?. Para mais informações sobre como conseguir o ID do cliente, consulte a documentação do Google Analytics.

      function() {
 var tracker = ga.getByName('UA-XXXXXX-N');
 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 de eventos do usuário à Vertex AI para Pesquisa para varejo.

  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 à sua tag na parte superior do painel (o marcador é Variável sem título), como "Vertex AI para Pesquisa 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.

    Suas 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 Vertex AI para Pesquisa 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 (recomendado): selecione se a implementação será uma das seguintes:

      • Você implementou o comércio eletrônico do Google Analytics pelo Gerenciador de tags. Reutilize a camada de dados como a fonte de dados de eventos, em vez de preencher uma nova. Ela usa o esquema do Google Analytics 4, se houver. Caso contrário, ele usa o e-commerce avançado do UA. Com essa fonte de dados, você só pode registrar 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. Confira Criar uma variável de consulta de pesquisa.

      • Você está usando o comércio eletrônico do Google Analytics e pode preencher manualmente o código da camada de dados. Consulte o guia para desenvolvedores sobre o 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. Escolha essa opção se não usar o e-commerce do Google Analytics ou se o e-commerce do Google Analytics não tiver os dados necessários para a Vertex AI para Pesquisa para varejo. Se você estiver mudando para essa origem a partir 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 esta opção Variável – Cloud Retail.

    • Variável – e-commerce: selecione se você não estiver usando o e-commerce do Google Analytics na sua camada de dados e não puder preencher manualmente o código dela.

      No campo Ler dados de comércio eletrônico da variável de usuário exibido, escolha uma variável. Assim, a Vertex AI para Pesquisa para varejo lê os 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 ou no Guia para desenvolvedores de e-commerce avançado. Para criar uma variável no formato correto, use o Criador de objetos de e-commerce avançado, um modelo de variável personalizada da galeria de modelos da comunidade do Gerenciador de tags. Os modelos da comunidade não são mantidos pelo Google. Para usar esse modelo, acesse a página da galeria do Criador de objetos de e-commerce avançado para conferir a documentação e outros recursos.

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

  9. Para o Seletor de campo, selecione visitorId como o campo e, em Valor do campo, selecione a nova variável de ID do visitante criada em Criar uma variável de ID do visitante.

  10. Clique em Salvar.

    Sua tag do Cloud Retail foi criada.

Opções da fonte de dados legada

Anteriormente, as opções Camada de dados – e-commerce e 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 tags novas. Se você mudar uma tag atual para uma nova fonte de dados, visualize-a com o Gerenciador de tags para verificá-la antes da implantação. Ao mudar:

  • Se você usou Camada de dados: e-commerce, é possível mudar para Camada de dados. Ela usa o esquema do Google Analytics 4, se houver. Caso contrário, ele usa o e-commerce avançado do UA.

  • Se você 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 a associe à opção Variável – Cloud Retail.

Próximo:

Criar uma variável de consulta de pesquisa

Se você estiver usando a pesquisa, poderá criar uma variável no Gerenciador de tags para consultas de pesquisa e anexá-la à sua tag do Cloud Retail. Assim, a Vertex AI para Pesquisa para varejo pode receber consultas de pesquisa do Analytics.

Os tipos de variáveis criadas dependem da fonte 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 à sua tag do Cloud Retail. Além disso, ative a opção da tag para usar 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 evento de um usuário é search, também é preciso:
    • 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 sua 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 as consultas de pesquisa inseridas no seu 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 personalizada (página). A opção criada e a configuração dela dependem da implementação do seu 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ê quiser formatar dados existentes no esquema de e-commerce ou varejo 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 a seguir e cole-as no painel JavaScript personalizado.

    3. No painel JavaScript personalizado, adicione o código JavaScript que retorna um evento de pesquisa no Retail Schema.

      O exemplo de código a seguir transforma os dados de uma variável Ecommerce Items na matriz productDetails usada pelo esquema da Vertex AI para Pesquisa para 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 de eventos de usuário da sua tag for Variável – e-commerce ou 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 recebidos 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

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

Ao criar uma variável de tipo constante para eventos de pesquisa e defini-la como uma substituição de evento do usuário na tag do Cloud Retail, a Vertex AI para Pesquisa para varejo pode determinar se o tipo de evento de um usuário é search.

Como alternativa a este procedimento, especifique o tipo de evento de usuário search usando a camada de dados ou a variável do Cloud Retail que você está usando como origem do evento da sua 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 gatilhos para todos os tipos de evento de usuário que os modelos da Vertex AI para Pesquisa para varejo usarão.

As tags do Gerenciador de tags precisam ter acionadores que controlam quando a tag deve ser "disparada" no site. Os gatilhos detectam quando ocorrem eventos (como um usuário visualizar a página inicial ou adicionar um item ao carrinho) e solicitam que sua tag envie informações desse evento do usuário para a Vertex AI para Pesquisa 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 para Pesquisa 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:

Crie 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 qualquer evento de usuário necessário para os modelos da Vertex AI para Pesquisa para varejo. 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 exigidos pelos seus modelos da Vertex AI para Pesquisa:

  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ê implementou o e-commerce do Google Analytics pelo Gerenciador de tags, reutilize os acionadores de eventos do e-commerce do Google Analytics para a Vertex AI para Pesquisa para varejo.

Com essa fonte de dados, você só pode registrar 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. Confira Criar uma variável de consulta de pesquisa.

A tabela a seguir mostra como os eventos de e-commerce e e-commerce avançado do Google Analytics são mapeados para eventos da Vertex AI para Pesquisa para 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ê:

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

  1. Na página Gerenciador de tags, Tags, clique na sua tag de e-commerce do Google Analytics (tipo de tag Google Analytics – Universal Analytics ou Google Analytics – Evento do GA4) para editá-la.

  2. Em Configurações avançadas > Sequenciamento de tags, selecione Disparar uma tag depois do disparo de <nome da tag de e-commerce avançado ou 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 e-commerce avançado ou GA4> falhar ou estiver pausado.

  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 eventos do usuário lista todos os campos e exemplos obrigatórios dos tipos de evento que precisam ser transmitidos para a 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 do console do Search for Retail. Esta página registra a maioria dos erros, exceto os de sintaxe, que normalmente aparecem apenas nos resultados das solicitações.

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.

Registrar 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 do lado do servidor com vários 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 desejada para usuários que querem maximizar o desempenho dos sites.

A outra vantagem da inclusão de tags no servidor é que uma única tag também pode ser compatível com muitos clientes upstream, por exemplo, na Web e em dispositivos móveis. Saiba como configurar a inclusão de tags no servidor.

A Vertex AI para Pesquisa para varejo fornece sua 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 de campos-chave, 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 não é possível definir a fonte de dados. A fonte de dados das tags do servidor é um fluxo de dados enviado da tag do Google no esquema do GA4.

Configurar a tag do Cloud Retail

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.

Acessar eventos gravados

Veja as métricas de integração de eventos na guia Eventos da página Dados do console do Search for Retail. Esta página mostra todos os eventos gravados ou importados no último ano. Pode levar até uma hora para que as métricas apareçam no console após a ingestão de dados bem-sucedida.

Acessar a página "Dados"

A seguir