Sobre os eventos do usuário

Nesta página, descrevemos o objeto de evento do usuário, incluindo a listagem de possíveis tipos de evento do usuário, e fornecemos amostras de dados para todos os tipos de evento do usuário.

A Vertex AI para Pesquisa no comércio usa eventos do usuário em tempo real para gerar recomendações e resultados de pesquisa. Quando você faz o upload de dados, as recomendações e a pesquisa podem usar esses dados. Portanto, não é necessário fazer o upload dos mesmos eventos duas vezes se você usa os dois serviços.

Como a atribuição de pesquisa funciona

Como a atribuição funciona

Tipos de evento do usuário

Há vários tipos de eventos de usuário que podem ser registrados conforme os usuários navegam no seu site de varejo:

Nome do evento do usuário Ação do usuário Google Analytics 4 event_name
home-page-view Exibe a página inicial. view_homepage
search (Pesquisar e navegar) Pesquisa no catálogo. view_item_list + [searchQuery OU pageCategories + filter]
category-page-view (somente recomendações) Exibe páginas especiais, como páginas de promoção. view_item_list + pageCategories
Visualização da página de detalhes Exibe a página de detalhes do produto. view_item
add-to-cart Adiciona o produto ao carrinho. add_to_cart
shopping-cart-page-view Exibe o carrinho de compras. begin_checkout
Compra concluída Conclui a finalização da compra. purchase

Para uma lista completa dos campos de eventos do GA4, consulte Campos de eventos do usuário do Google Analytics 4.

Para informações detalhadas sobre o objeto UserEvent, consulte UserEvent.

Prioridade do tipo de evento

Para ver os melhores resultados, sugerimos registrar os eventos do usuário para todos os tipos de evento. A tabela a seguir descreve a prioridade dos diferentes tipos de eventos do usuário. É necessário registrar eventos do usuário de prioridade mais alta para alcançar modelos de dados de qualidade.

Prioridade Tipos de evento do usuário

Obrigatório para o experimento dinâmico inicial de recomendações

(os tipos de evento dependem do tipo de modelo de recomendação)

detail-page-view

add-to-cart

purchase-complete

home-page-view
Evento extra necessário para o experimento dinâmico de pesquisa

search

Requisitos e práticas recomendadas de eventos do usuário

As tabelas a seguir listam os requisitos e as práticas recomendadas para tipos de evento do usuário usados pelas recomendações e pela pesquisa. Verifique se os eventos do usuário atendem a esses requisitos para que a Vertex AI para Pesquisa no comércio possa gerar resultados de qualidade.

Nesta seção estão listados:

Se você usa modelos de recomendação, consulte também Requisitos de dados do tipo de modelo, que lista outros requisitos, dependendo do tipo de modelo de recomendação e do objetivo de otimização que você planeja usar.

É possível conferir as métricas de qualidade de dados da pesquisa na página Qualidade de dados no console da Pesquisa para e-commerce. Essas métricas mostram as porcentagens de produtos e eventos do usuário que atendem aos padrões recomendados de qualidade dos dados. Para informações sobre como ver a qualidade dos dados de pesquisa, consulte Desbloquear níveis de desempenho da pesquisa.

Requisitos gerais de eventos do usuário

Verifique se os eventos do usuário atendem aos requisitos a seguir para que a Vertex AI para Pesquisa no comércio possa gerar resultados de qualidade. Elas se aplicam a recomendações e pesquisa.

Tipo de evento Requisito Impacto
Todos os eventos

Não inclua dados sintéticos ou eventos duplicados.

Eventos sintéticos ou duplicados afetam negativamente a qualidade do modelo e geralmente impedem o treinamento bem-sucedido. Eventos duplicados podem resultar em valores incorretos de métricas.

Inclua pelo menos 100 IDs de visitantes únicos para cada tipo de evento processado.

Isso verifica se a Vertex AI para Pesquisa de comércio tem dados suficientes para gerar resultados de qualidade.

Os IDs de visitantes precisam ser formatados exatamente da mesma maneira na importação ou no registro de eventos e nas solicitações de API.

Usar um formato consistente para IDs de visitantes ajuda a identificar corretamente os padrões de visitantes e oferecer resultados de melhor qualidade com base no comportamento do usuário.

Os produtos incluídos nos eventos precisam constar no catálogo de produtos.

A proporção de eventos não associados deve ser a mais baixa possível. Uma proporção alta pode afetar negativamente a qualidade da recomendação ou dos resultados da pesquisa.

Os dados de eventos não integrados não são usados para treinar modelos. No entanto, os eventos não associados podem ser associados mais tarde, depois que os produtos associados forem ingeridos. Para mais informações, consulte Reunir eventos do usuário.

Alguns eventos de usuário precisam ter o mesmo ID de visitante.

Para criar históricos de sequência de comportamento válidos, a Vertex AI Search para e-commerce precisa conseguir ver vários eventos com o mesmo ID de visitante.

Por exemplo, visitor123 visualizou cinco páginas de detalhes do produto, adicionou três produtos ao carrinho e comprou dois dos cinco produtos originais. Se todos esses eventos fornecerem o mesmo ID de visitante formatado de maneira consistente, a Pesquisa da Vertex AI para e-commerce poderá considerar essa sequência de comportamento nos modelos.

detail-page-view

Inclua exatamente um produto por evento.

O evento não poderá ser usado se não houver um produto. Se vários produtos forem incluídos, o evento será considerado incorreto e não poderá ser usado.

add-to-cart

Inclua exatamente um produto por evento.

Se vários produtos forem incluídos, o evento será considerado incorreto e não poderá ser usado.

purchase-complete

Inclua purchase_transaction.revenue.

Os eventos purchase-complete que não têm o campo revenue não são usados para treinar modelos.

Inclua exatamente um purchase_transaction.currency_code em todos os eventos de compra.

Não há um código de moeda padrão. É necessário fornecer um código.

Os eventos de compra sem esse campo resultam em métricas de receita incorretas.

Verifique se alguns eventos de compra incluem vários produtos.

Ter alguns eventos de compra com vários produtos ajuda o modelo a aprender padrões de compra conjunta.

Requisitos específicos do Recommendations

Se você estiver usando recomendações, verifique se os eventos do usuário atendem aos requisitos a seguir.

Se você usa modelos de recomendação, consulte também Requisitos de dados do tipo de modelo, que lista outros requisitos, dependendo do tipo de modelo de recomendação e do objetivo de otimização que você planeja usar.

Tipo de evento Requisito Impacto
purchase-complete

Não nivele cestas com vários itens em vários eventos de compra. Elas devem permanecer como eventos de compra únicos que incluem vários produtos.

Isso verifica se padrões de compra conjunta válidos são gerados.

Requisitos específicos da pesquisa

Se você estiver usando a pesquisa, verifique se os eventos do usuário atendem aos requisitos mínimos a seguir para receber resultados.

Tipo de evento Requisito Impacto
search

searchQuery precisa existir para eventos de pesquisa, e pageCategories precisa existir para eventos de navegação.

Não incluir esse campo pode afetar muito negativamente a qualidade e as métricas dos resultados da pesquisa.

Nas solicitações de pesquisa, o ID do visitante precisa corresponder ao ID de visitante enviado nos eventos relacionados a essa solicitação de pesquisa.

Caso contrário, os eventos são considerados incorretos e as métricas podem estar erradas.

Nos eventos de pesquisa, a lista de IDs de produto precisa corresponder à lista de produtos exibida ao usuário na íntegra.

Se eles não corresponderem, o impacto negativo na qualidade do resultado da pesquisa poderá ser grave e as métricas estarão incorretas.

Se a pesquisa usa um filtro, filter precisa existir e analisar corretamente.

Se esse campo não existir, a Vertex AI para Pesquisa para Commerce não poderá usar a parte de filtro dos dados, o que pode afetar negativamente a qualidade do resultado da pesquisa.

Inclua o campo attribution_token para vincular outros eventos de volta aos eventos de pesquisa.

Não incluir um token de atribuição vai gerar um erro na Pesquisa para e-commerce e afetar muito negativamente a qualidade da pesquisa e a precisão das métricas.

Requisitos de otimização da pesquisa

Para permitir que a pesquisa otimize automaticamente a experiência de pesquisa com base nas tendências gerais dos usuários, faça upload dos seguintes dados.

Os eventos precisam ser enviados pelo menos diariamente, com um atraso máximo de 24 horas.

Métrica de eventos Volume/frequência de eventos Descrição
Volume de eventos de search 250 mil nos últimos 90 dias

Pelo menos 250.000 eventos nos últimos 90 dias são necessários para otimizar a experiência de pesquisa com base nos eventos ingeridos.

Recomendamos fazer upload de eventos pelo menos uma vez por dia para manter uma boa qualidade dos dados. Durante as importações de eventos históricos, verifique se a distribuição de dados está inclinada para o carimbo de data/hora mais recente. O número de eventos no último dia de carimbo de data/hora precisa ser igual ou maior que a média diária de eventos.
Volume de detail-page-view atribuído a um evento de search 500.000 nos últimos 30 dias Pelo menos 500.000 eventos são necessários para otimizar os resultados da pesquisa usando eventos do usuário.
Média de eventos detail-page-view atribuíveis a um evento search por produto 10 nos últimos 30 dias Obrigatório para otimizar os resultados da pesquisa usando os eventos ingeridos, a menos que os eventos dos últimos 21 dias sejam enviados.
Proporção de eventos search com filtros analisáveis 0,1 nos últimos 30 dias Recomendado para otimizar a ordem dos atributos dinâmicos na resposta da pesquisa.
Proporção de produtos pesquisados com preço 0,95 nos últimos 30 dias Obrigatório para otimizar os resultados da pesquisa usando os eventos ingeridos.
Média de eventos add-to-cart atribuíveis a um evento search por produto pago 0,5 nos últimos 30 dias Recomendado para resultados da pesquisa otimizados para receita.
Média de eventos purchase-complete atribuíveis a um evento search por produto pesquisável com preço 0,5 nos últimos 30 dias Recomendado para resultados da pesquisa otimizados para receita.

Requisitos de personalização da Pesquisa

A Pesquisa exige os seguintes dados para personalizar a pesquisa de texto e navegar pelos resultados da pesquisa dos usuários com base na atividade deles.

Depois de fazer upload dos dados a seguir, a Pesquisa pode personalizar os resultados automaticamente.

Métrica de eventos Volume/frequência de eventos Descrição
Volume de eventos de search veiculados pela pesquisa 100.000 nos últimos 30 dias

É preciso ter pelo menos 100 mil eventos veiculados pela pesquisa nos últimos 30 dias para oferecer personalização.

Os resultados da pesquisa não são armazenados em cache Menos de 1% dos 100 mil eventos de usuário mais recentes

Não armazene em cache os resultados da pesquisa de texto ou navegação se você planeja usar a personalização. Reutilizar os mesmos resultados para todos os visitantes impede que a pesquisa ofereça resultados realmente personalizados a qualquer usuário e expõe os dados particulares deles. A Pesquisa desativa automaticamente a personalização se o armazenamento em cache for detectado.

Se você armazenar em cache apenas os resultados da pesquisa, ela ainda poderá personalizar os resultados da navegação. Por outro lado, se você armazenar em cache apenas os resultados de navegação, a pesquisa ainda poderá personalizar os resultados da pesquisa de consultas de texto.

Correspondências de ID do visitante entre SearchRequests e eventos do usuário Mais de 10% de correspondência para os 100 mil eventos de usuário mais recentes Verifique se o espaçamento e a formatação do ID do visitante correspondem em SearchRequests e nos eventos do usuário. A formatação consistente do ID do visitante verifica se a pesquisa pode identificar a atividade do usuário corretamente.

Exemplos e esquemas de tipo de evento do usuário

Nesta seção, apresentamos os formatos de dados para cada tipo de evento compatível.

São fornecidos exemplos do JavaScript Pixel e do Gerenciador de tags. Para o BigQuery, é fornecido o esquema de tabela completo para cada tipo.

Para todos os tipos de eventos do usuário, userId é opcional. Os campos de informações do produto (priceInfo e availability) são opcionais.

Algumas considerações:

  • O campo experimentIds é necessário somente se você estiver executando um experimento A/B.
  • O campo attributionToken é obrigatório apenas para a Vertex AI para Pesquisa para Commerce. Ele é usado para medir a performance. Os tokens de atribuição não devem ser enviados para predict, search e detail-page-view nem para eventos de clique.
  • Certifique-se de que todos os seus eventos usem uma única moeda, principalmente se você pretende usar o console doGoogle Cloud para ver métricas de receita. A API Vertex AI Search para Commerce não é compatível com o uso de várias moedas por catálogo.

Para mais detalhes sobre o objeto de evento do usuário, consulte a documentação de referência da API UserEvent.

Adicionar ao carrinho

Veja a seguir o formato de evento do usuário add-to-cart.

Os exemplos a seguir mostram apenas os campos obrigatórios para o formato de evento do usuário add-to-cart.

Ao importar eventos, é necessário informar o carimbo de data/hora no campo eventTime no formato especificado pela RFC 3339.

Outros campos podem ser obrigatórios dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a uma entidade, especifique o campo entity. Para saber todos os detalhes de cada campo e quando eles são obrigatórios, consulte a documentação de referência da API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "add-to-cart",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    },
    "quantity": { "value": product-quantity }
  }]
};

Gerenciador de tags 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'add-to-cart',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          },
          'quantity': product-quantity
        }]
      }
    });
</script>

BigQuery

Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.

Os modos dos campos obrigatórios estão definidos como REQUIRED ou REPEATED. Os modos dos campos opcionais são definidos como NULLABLE.

Observe que eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato de carimbo de data/hora. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Visualização da página de categoria

Veja a seguir o formato de evento do usuário category-page-view.

Os exemplos a seguir mostram apenas os campos obrigatórios para o formato de evento do usuário category-page-view.

Embora geralmente haja apenas uma categoria associada a uma página, o campo pageCategories também é compatível com uma hierarquia de categorias, que pode ser fornecida em forma de lista.

Ao importar eventos, é necessário informar o carimbo de data/hora no campo eventTime no formato especificado pela RFC 3339.

Outros campos podem ser obrigatórios dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a uma entidade, especifique o campo entity. Para saber todos os detalhes de cada campo e quando eles são obrigatórios, consulte a documentação de referência da API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "category-page-view",
  "visitorId": "visitor-id",
  "pageCategories": ["category1 > category2"]
};

Gerenciador de tags 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'category-page-view',
        'visitorId": 'visitor-id',
        // You can also define the user ID and visitor ID
        // directly on the Tag Manager tag.
        'pageCategories': ['category1 > category2']
      }
    });
</script>

BigQuery

Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.

Os modos dos campos obrigatórios estão definidos como REQUIRED ou REPEATED. Os modos dos campos opcionais são definidos como NULLABLE.

Observe que eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato de carimbo de data/hora. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Visualização da página de detalhes

Veja a seguir o formato de dados de evento do usuário detail-page-view.

Os exemplos a seguir mostram apenas os campos obrigatórios para o formato de evento do usuário detail-page-view.

Na maioria dos casos, productDetails contém detalhes do produto associado, exceto se os itens estiverem sendo vendidos juntos, como um pacote.

Ao importar eventos, é necessário informar o carimbo de data/hora no campo eventTime no formato especificado pela RFC 3339.

Outros campos podem ser obrigatórios dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a uma entidade, especifique o campo entity. Para saber todos os detalhes de cada campo e quando eles são obrigatórios, consulte a documentação de referência da API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "detail-page-view",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    }
  }]
};

Gerenciador de tags 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'detail-page-view',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID directly on
        // the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          }
        }]
      }
    });
</script>

BigQuery

Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.

Os modos dos campos obrigatórios estão definidos como REQUIRED ou REPEATED. Os modos dos campos opcionais são definidos como NULLABLE.

Observe que eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato de carimbo de data/hora. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Visualização da página inicial

Veja a seguir o formato de evento do usuário home-page-view.

Os exemplos a seguir mostram apenas os campos obrigatórios para o formato de evento do usuário home-page-view.

Ao importar eventos, é necessário informar o carimbo de data/hora no campo eventTime no formato especificado pela RFC 3339.

Outros campos podem ser obrigatórios dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a uma entidade, especifique o campo entity. Para saber todos os detalhes de cada campo e quando eles são obrigatórios, consulte a documentação de referência da API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "home-page-view",
  "visitorId": "visitor-id",
};

Gerenciador de tags 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'home-page-view',
        'visitorId': 'visitor-id'
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
      }
    });
</script>

BigQuery

Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.

Os modos dos campos obrigatórios estão definidos como REQUIRED ou REPEATED. Os modos dos campos opcionais são definidos como NULLABLE.

Observe que eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato de carimbo de data/hora. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Compra concluída

Veja a seguir o formato de dados de evento do usuário purchase-complete.

Os exemplos a seguir mostram apenas os campos obrigatórios para o formato de evento do usuário purchase-complete.

Ao importar eventos, é necessário informar o carimbo de data/hora no campo eventTime no formato especificado pela RFC 3339.

Outros campos podem ser obrigatórios dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a uma entidade, especifique o campo entity. Para saber todos os detalhes de cada campo e quando eles são obrigatórios, consulte a documentação de referência da API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "purchase-complete",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    },
    "quantity": product-quantity
  }],
  "purchaseTransaction": {
    "revenue": revenue,
    "currencyCode": "currency-code"
  }
};

Gerenciador de tags 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'purchase-complete',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID directly on
        // the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          },
          'quantity': product-quantity
        }],
        'purchaseTransaction': {
          'revenue': revenue,
          'currencyCode': 'currency-code'
        }
      }
    });
</script>

BigQuery

Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.

Os modos dos campos obrigatórios estão definidos como REQUIRED ou REPEATED. Os modos dos campos opcionais são definidos como NULLABLE.

Observe que eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato de carimbo de data/hora. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         },
         {
           "name": "priceInfo",
           "type": "RECORD",
           "mode": "NULLABLE",
           "fields": [
             {
               "name": "price",
               "type": "FLOAT",
               "mode": "REQUIRED"
             },
             {
               "name": "originalPrice",
               "type": "FLOAT",
               "mode": "NULLABLE"
             },
             {
               "name": "currencyCode",
               "type": "STRING",
               "mode": "REQUIRED"
             },
             {
               "name": "cost",
               "type": "FLOAT",
               "mode": "NULLABLE"
             }
           ]
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "purchaseTransaction",
   "type": "RECORD",
   "mode": "REQUIRED",
   "fields": [
     {
       "name": "id",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "revenue",
       "type": "FLOAT",
       "mode": "REQUIRED"
     },
     {
       "name": "tax",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "cost",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "currencyCode",
       "type": "STRING",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Veja a seguir o formato de evento do usuário search.

Objeto search mínimo necessário

Estes são os campos mínimos necessários para que a Vertex AI para Pesquisa para Commerce retorne uma lista de resultados da pesquisa:

  • searchQuery é lido do parâmetro search_term ou dos eventos view_search_results.
  • productDetails é lido do parâmetro items do evento view_item_list. Ela precisa incluir a lista de IDs de produto mostrados ao usuário final na página de resultados da pesquisa.
  • O userEvents captura todas as informações de metadados que a API Retail precisa saber sobre como os usuários finais interagem com o site do cliente.

Os exemplos a seguir mostram apenas os campos obrigatórios para o formato de evento do usuário search.

Ao importar eventos, é necessário informar o carimbo de data/hora no campo eventTime no formato especificado pela RFC 3339.

Outros campos podem ser obrigatórios dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a uma entidade, especifique o campo entity. Para saber todos os detalhes de cada campo e quando eles são obrigatórios, consulte a documentação de referência da API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "search",
  "visitorId": "visitor-id",
  "searchQuery": "search-query",
  "pageCategories": ["category1 > category2"],
  "productDetails": [
    {
      "product": {
        "id": "product-id1"
      }
    }, {
      "product": {
        "id": "product-id2"
      }
    }
  ]
};

Gerenciador de tags 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'search',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'searchQuery': 'search-query',
        'pageCategories': ['category1 > category2'],
        'productDetails': [
          {
            'product': {
              'id': 'product-id1'
            }
          }, {
            'product': {
              'id': 'product-id2'
            }
          }
        ]
      }
    });
</script>

BigQuery

Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.

Os modos dos campos obrigatórios estão definidos como REQUIRED ou REPEATED. Os modos dos campos opcionais são definidos como NULLABLE.

Observe que eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato de carimbo de data/hora. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "searchQuery",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Preenchimento automático

Esse campo só é obrigatório para eventos de pesquisa se você quiser usar o preenchimento automático. Não é necessário para a pesquisa.

Os exemplos a seguir mostram o campo completionDetail quando um usuário digita "sa" e clica na segunda sugestão, "sapatos", na lista de sugestões para acionar um evento de pesquisa. Se o usuário não clicar em nenhuma sugestão, o campo completionDetail vai permanecer vazio.

eventType precisa ser "search".

completionAttributionToken é o attributionToken da resposta completeQuery.

selectedSuggestion precisa ser igual a searchQuery.

JavaScript Pixel

var user_event = {
  "eventType": "search",
  "visitorId": "visitor-id",
  "searchQuery": "search-query",
  "pageCategories": ["category1 > category2"],
  "productDetails": [
    {
      "product": {
        "id": "product-id1"
      }
    }, {
      "product": {
        "id": "product-id2"
      }
    }
  ]
  "completionDetail": {
    "completionAttributionToken": "completion_token",
    "selectedSuggestion": "search-query",
    "selectedPosition": completion_position
  }
};

Gerenciador de tags 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'search',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'searchQuery': 'search-query',
        'pageCategories': ['category1 > category2'],
        'productDetails': [
          {
            'product': {
              'id': 'product-id1'
            }
          }, {
            'product': {
              'id': 'product-id2'
            }
          }
        ]
        "completionDetail": {
          "completionAttributionToken": 'completion_token',
          "selectedSuggestion": 'search-query',
          "selectedPosition": completion_position
        }
      }
    });
</script>

BigQuery

Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.

Os modos dos campos obrigatórios estão definidos como REQUIRED ou REPEATED. Os modos dos campos opcionais são definidos como NULLABLE.

Observe que eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato de carimbo de data/hora. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "searchQuery",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "completionDetail",
   "type": "RECORD"
   "mode": "NULLABLE"
   "fields": [
     {
       "name": "completionAttributionToken",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "selectedSuggestion",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "selectedPosition",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
    ]
 }
]

Visualização da página do carrinho de compras

Veja a seguir o formato de dados de evento do usuário shopping-cart-page-view.

Os exemplos a seguir mostram apenas os campos obrigatórios para o formato de evento do usuário shopping-cart-page-view.

Forneça os objetos productDetails e userEvents, exceto se o carrinho de compras estiver vazio.

Ao importar eventos, é necessário informar o carimbo de data/hora no campo eventTime no formato especificado pela RFC 3339.

Outros campos podem ser obrigatórios dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a uma entidade, especifique o campo entity. Para saber todos os detalhes de cada campo e quando eles são obrigatórios, consulte a documentação de referência da API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "shopping-cart-page-view"",
  "visitorId": "VISITOR-ID"
  "cartId": "CART-ID",
  "productDetails": [{
      "product": {
        "id": "PRODUCT-ID"
      },
      "quantity": PRODUCT-QUANTITY
    }]
};

Substitua PRODUCT-ID, PRODUCT-QUANTITY, VISOTOR-ID e CART-ID pelo ID do produto, quantidade de produtos, ID da sessão e ID do carrinho de compras.

Gerenciador de tags 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'shopping-cart-page-view',
        'visitorId': 'VISITOR-ID'
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'cartId': 'CART-ID',
        'productDetails': [{
            'product': {
              'id': 'PRODUCT-ID'
            },
            'quantity': PRODUCT-QUANTITY
          }]
      }
    });
</script>

Substitua PRODUCT-ID, PRODUCT-QUANTITY, VISOTOR-ID e CART-ID pelo ID do produto, quantidade de produtos, ID da sessão e ID do carrinho de compras.

BigQuery

Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.

Os modos dos campos obrigatórios estão definidos como REQUIRED ou REPEATED. Os modos dos campos opcionais são definidos como NULLABLE.

Observe que eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato de carimbo de data/hora. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Campos de eventos do usuário do Google Analytics 4

A tabela a seguir mostra como os campos de eventos do usuário do Google Analytics 4 são mapeados para os campos da Pesquisa da Vertex AI para e-commerce.

Antes de importar ou registrar eventos de usuário do Google Analytics 4, verifique se eles usam os seguintes campos para que a Pesquisa da Vertex AI para e-commerce possa integrar seus dados corretamente.

Google Analytics 4 Varejo
ecommerce.purchase_revenue purchaseTransaction.revenue
event_name eventType
event_timestamp eventTime
items.item_id productDetails.product.id
items.price productDetails.product.priceInfo.price
items.quantity productDetails.quantity
Chave:
event_params.key definida como "currency"

Valor:
event_params.value.string_value		 productDetails.product.priceInfo.currencyCode
Chave:
event_params.key definida como "currency"

Valor:
event_params.value.string_value		 purchaseTransaction.currencyCode
Chave:
event_params.key definida como "search_term"

Valor:
event_params.value.string_value		 searchQuery
user_id userInfo.userId
user_pseudo_id visitorId

A seguir