Acerca dos eventos do utilizador

Esta página descreve o objeto de evento do utilizador, incluindo a enumeração de potenciais tipos de eventos do utilizador, e fornece dados de exemplo para todos os tipos de eventos do utilizador.

A Vertex AI Search for commerce usa eventos de utilizadores em tempo real para gerar recomendações e resultados da pesquisa. Quando carrega dados, as recomendações e a pesquisa podem usar esses dados, pelo que não tem de carregar os mesmos eventos duas vezes se usar ambos os serviços.

Como funciona a atribuição de pesquisas

Como funciona a atribuição

Tipos de eventos do utilizador

Existem vários tipos de eventos do utilizador que pode registar à medida que os utilizadores navegam no seu site de retalho:

Nome do evento do utilizador Ação do utilizador Google Analytics 4 event_name
home-page-view Vê a página inicial. view_homepage
pesquisar (pesquisar e procurar) Pesquisa no catálogo. view_item_list + [searchQuery OU pageCategories + filter]
category-page-view (apenas recomendações) Visualiza páginas especiais, como páginas de saldos ou promoções. view_item_list + pageCategories
detail-page-view Visualiza a página de detalhes do produto. view_item
add-to-cart Adiciona o produto ao carrinho. add_to_cart
shopping-cart-page-view Vê o carrinho de compras. begin_checkout
purchase-complete Conclui o pagamento. purchase

Para ver uma lista exaustiva dos campos de eventos do GA4, consulte o artigo Campos de eventos do utilizador do Google Analytics 4.

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

Prioridade do tipo de evento

Para obter resultados da mais alta qualidade, recomendamos que registe eventos do utilizador para todos os tipos de eventos. A tabela seguinte descreve a prioridade dos diferentes tipos de eventos do utilizador. Tem de registar os eventos do utilizador de prioridade mais elevada para alcançar modelos de dados de qualidade.

Prioridade Tipos de eventos do utilizador

Necessário para a experimentação inicial em direto para recomendações

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

detail-page-view

add-to-cart

purchase-complete

home-page-view
Evento adicional necessário para a experiência em direto de pesquisa

search

Requisitos e práticas recomendadas para eventos de utilizador

As tabelas seguintes listam os requisitos e as práticas recomendadas para os tipos de eventos de utilizadores que as recomendações e a pesquisa usam. Verifique se os seus eventos de utilizador cumprem estes requisitos para que o Vertex AI Search for commerce possa gerar resultados de qualidade.

Esta secção apresenta:

Se usar modelos de recomendações, consulte também os requisitos de dados do tipo de modelo, que indicam requisitos adicionais consoante o tipo de modelo de recomendações e o objetivo de otimização que planeia usar.

Pode ver as métricas de qualidade de dados para a pesquisa na página Qualidade de dados na consola de pesquisa para comércio. Estas métricas mostram as percentagens de produtos e eventos de utilizadores que cumprem as normas recomendadas de qualidade dos dados. Para ver informações sobre como ver a qualidade dos dados de pesquisa, consulte o artigo Desbloqueie os níveis de desempenho da pesquisa.

Requisitos gerais de eventos de utilizador

Certifique-se de que os eventos do utilizador cumprem os seguintes requisitos para que a Pesquisa Vertex AI para comércio possa gerar resultados de qualidade. Estas aplicam-se tanto às recomendações como à pesquisa.

Tipo de evento Requisito Impacto
Todos os eventos

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

Os eventos sintéticos ou duplicados afetam negativamente a qualidade do modelo e, muitas vezes, impedem a preparação bem-sucedida do modelo. Os eventos duplicados podem causar valores de métricas incorretos.

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

Isto verifica se o Vertex AI Search para comércio tem dados suficientes para gerar resultados de qualidade.

Os IDs de visitantes têm de ter exatamente o mesmo formato na importação de eventos ou na gravação de eventos e nos pedidos da API.

A utilização de um formato consistente para os IDs dos visitantes ajuda a identificar corretamente os padrões dos visitantes e a fornecer resultados de melhor qualidade com base no comportamento do utilizador.

Os produtos incluídos nos eventos devem existir no seu catálogo de produtos.

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

Os dados de eventos não associados não são usados para preparar modelos. No entanto, os eventos não associados podem ser associados mais tarde, após a ingestão dos produtos associados. Para mais informações, consulte o artigo Volte a juntar eventos de utilizadores.

Alguns eventos do utilizador devem ter o mesmo ID do visitante.

Para criar históricos de sequências de comportamento válidos, o Vertex AI Search for commerce tem de conseguir ver vários eventos com o mesmo ID do visitante.

Por exemplo, visitor123 visualizou cinco páginas de detalhes de produtos, adicionou três produtos ao carrinho e, em seguida, comprou dois dos cinco produtos originais. Se estes eventos fornecerem todos o mesmo ID do visitante formatado de forma consistente, a Vertex AI Search for commerce pode considerar essa sequência de comportamento nos respetivos modelos.

detail-page-view

Inclua exatamente um produto por evento.

Não é possível usar o evento se não existir nenhum produto. Se forem incluídos vários produtos, o evento está formatado incorretamente e não pode ser usado.

add-to-cart

Inclua exatamente um produto por evento.

Se forem incluídos vários produtos, o evento está formatado incorretamente e não pode 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 preparar modelos.

Inclua exatamente um purchase_transaction.currency_code em todos os eventos purchase.

Não existe um código de moeda predefinido. Tem de fornecer um código.

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

Verifique se alguns eventos purchase 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 das recomendações

Se estiver a usar recomendações, certifique-se de que os eventos do utilizador cumprem os seguintes requisitos.

Se usar modelos de recomendações, consulte também os requisitos de dados do tipo de modelo, que indicam requisitos adicionais consoante o tipo de modelo de recomendações e o objetivo de otimização que planeia usar.

Tipo de evento Requisito Impacto
purchase-complete

Não reduza os cestos com vários artigos a vários eventos de compra. Devem permanecer como eventos de compra únicos que incluem vários produtos.

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

Requisitos específicos da Pesquisa

Se estiver a usar a pesquisa, certifique-se de que os seus eventos de utilizador cumprem os seguintes requisitos mínimos para obter resultados.

Tipo de evento Requisito Impacto
search

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

A não inclusão deste campo pode ter um impacto negativo grave na qualidade e nas métricas dos resultados da pesquisa.

O ID do visitante nos pedidos de pesquisa deve corresponder ao ID do visitante enviado em eventos relacionados com esse pedido de pesquisa.

Se não corresponderem, os eventos estão com erros de formato e as métricas podem estar incorretas.

A lista de IDs dos produtos nos eventos de pesquisa tem de corresponder à lista de produtos apresentada ao utilizador na íntegra.

Se não corresponderem, o impacto negativo na qualidade dos resultados da pesquisa pode ser grave e as métricas ficam incorretas.

Se a pesquisa usar um filtro, filter tem de existir e ser analisado corretamente.

Se este campo não existir, a Vertex AI Search for commerce não pode usar a parte do filtro dos dados, o que pode afetar negativamente a qualidade dos resultados da pesquisa.

Inclua o campo attribution_token para associar outros eventos a eventos de pesquisa.

A não inclusão de um token de atribuição aciona um erro na pesquisa de comércio e tem um impacto negativo grave na qualidade da pesquisa e na 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 utilizadores, carregue os seguintes dados.

Os eventos devem ser carregados, 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 do tipo search 250 mil nos últimos 90 dias

São necessários, pelo menos, 250 000 eventos nos últimos 90 dias para otimizar a experiência de pesquisa com base nos eventos carregados.

Recomendamos que carregue eventos, pelo menos, diariamente para manter uma boa qualidade dos dados. Durante as importações de eventos de histórico, certifique-se de que a distribuição de dados é enviesada para a data/hora mais recente. O número de eventos no último dia de data/hora deve ser igual ou superior à contagem média de eventos diários.
Volume de detail-page-view atribuível a um evento de search 500 000 nos últimos 30 dias São necessários, pelo menos, 500 000 eventos para otimizar os resultados da pesquisa através de eventos do utilizador.
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 através dos eventos carregados, a menos que os eventos dos últimos 21 dias sejam carregados.
Proporção de eventos search com filtros analisáveis 0,1 nos últimos 30 dias Recomendado para otimizar a ordem das facetas dinâmicas na resposta de pesquisa.
Proporção de produtos pesquisados com preço 0,95 nos últimos 30 dias Obrigatório para otimizar os resultados da pesquisa através dos eventos carregados.
Média de eventos add-to-cart atribuíveis a um evento search por produto com preço 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 com preço pesquisável 0,5 nos últimos 30 dias Recomendado para resultados da pesquisa otimizados para receita.

Requisitos de personalização da pesquisa

A Pesquisa requer os seguintes dados para personalizar a pesquisa de texto e os resultados da pesquisa de navegação para os seus utilizadores com base na respetiva atividade.

Depois de carregar os seguintes dados, a Pesquisa pode personalizar os resultados automaticamente.

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

São necessários, pelo menos, 100 000 eventos publicados pela pesquisa nos últimos 30 dias para oferecer personalização.

Os resultados da pesquisa não são colocados em cache Menos de 1% dos 100 000 eventos de utilizadores mais recentes

Não coloque em cache os resultados da pesquisa de texto nem as pesquisas de navegação se planear usar a personalização. A reutilização dos mesmos resultados em todos os visitantes impede que a pesquisa forneça resultados verdadeiramente personalizados a qualquer utilizador e corre o risco de expor os dados privados dos utilizadores. A Pesquisa desativa automaticamente a personalização se for detetada colocação em cache.

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

O ID de visitante corresponde entre o SearchRequests e os eventos do utilizador Mais de 10% de correspondência para os 100 000 eventos de utilizador mais recentes Certifique-se de que o espaçamento e a formatação dos IDs de visitantes correspondem nos SearchRequests e nos eventos de utilizadores. A formatação consistente do ID do visitante verifica se a pesquisa consegue identificar corretamente a atividade do utilizador.

Exemplos e esquemas de tipos de eventos de utilizadores

Esta secção fornece os formatos de dados para cada tipo de evento suportado.

São fornecidos exemplos para o píxel JavaScript e o Gestor de Etiquetas. Para o BigQuery, é fornecido o esquema completo da tabela para cada tipo.

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

Tenha em atenção que:

  • O campo experimentIds só é necessário se estiver a executar uma experiência A/B.
  • O campo attributionToken é obrigatório apenas para o Vertex AI Search para comércio. É usado para medir o desempenho. Os tokens de atribuição não devem ser enviados para predict, search e detail-page-view, nem para eventos de cliques.
  • Certifique-se de que todos os seus eventos usam uma única moeda, especialmente se planeia usar a Google Cloud consola para obter métricas de receita. A API Vertex AI Search for commerce não suporta a utilização de várias moedas por catálogo.

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

Adicionar ao carrinho

O exemplo seguinte mostra o formato de evento de utilizador add-to-cart apenas com os campos obrigatórios.

A quantidade de produtos num evento add-to-cart tem de ser um valor incremental que represente a quantidade do produto associado a esse evento de utilizador específico. Por exemplo, se forem adicionadas duas unidades de um produto ao carrinho de compras, o campo de quantidade para esse evento add-to-cart deve ser 2. Para eventos add-to-cart, inclua exatamente um produto por evento.

Quando importa eventos, tem de indicar a data/hora no campo eventTime no formato especificado pela RFC 3339.

Podem ser necessários outros campos consoante o método da API usado ou se forem usados campos adicionais. (Por exemplo, se o evento do utilizador estiver associado a uma entidade, certifique-se de que especifica o campo entity.) Para ver detalhes completos de cada campo e quando são obrigatórios, consulte a UserEvent documentação de referência da API.

Píxel de JavaScript

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

Gestor de Etiquetas 

<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 este tipo de evento de utilizador. Especifique este esquema quando criar tabelas para este tipo de evento do utilizador no BigQuery.

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

Tenha em atenção que o eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato 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

O exemplo seguinte mostra o formato do evento de utilizador category-page-view.

Os exemplos seguintes mostram apenas os campos obrigatórios do category-page-view formato de evento do utilizador.

Embora normalmente exista apenas uma categoria associada a uma página, o campo pageCategories também suporta uma hierarquia de categorias, que pode fornecer como uma lista.

Quando importa eventos, tem de indicar a data/hora no campo eventTime no formato especificado pela RFC 3339.

Podem ser necessários outros campos consoante o método da API usado ou se forem usados campos adicionais. (Por exemplo, se o evento do utilizador estiver associado a uma entidade, certifique-se de que especifica o campo entity.) Para ver detalhes completos de cada campo e quando são obrigatórios, consulte a UserEvent documentação de referência da API.

Píxel de JavaScript

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

Gestor de Etiquetas 

<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 este tipo de evento de utilizador. Especifique este esquema quando criar tabelas para este tipo de evento do utilizador no BigQuery.

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

Tenha em atenção que o eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato 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

O exemplo seguinte mostra o formato dos dados de eventos do utilizador detail-page-view.

Os exemplos seguintes mostram apenas os campos obrigatórios do detail-page-view formato de evento do utilizador.

Na maioria dos casos, productDetails contém detalhes do produto associado, a menos que esteja a ser vendido um conjunto de artigos.

Quando importa eventos, tem de indicar a data/hora no campo eventTime no formato especificado pela RFC 3339.

Podem ser necessários outros campos consoante o método da API usado ou se forem usados campos adicionais. (Por exemplo, se o evento do utilizador estiver associado a uma entidade, certifique-se de que especifica o campo entity.) Para ver detalhes completos de cada campo e quando são obrigatórios, consulte a UserEvent documentação de referência da API.

Píxel de JavaScript

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

Gestor de Etiquetas 

<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 este tipo de evento de utilizador. Especifique este esquema quando criar tabelas para este tipo de evento do utilizador no BigQuery.

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

Tenha em atenção que o eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato 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

O exemplo seguinte mostra o formato do evento de utilizador home-page-view.

Os exemplos seguintes mostram apenas os campos obrigatórios do home-page-view formato de evento do utilizador.

Quando importa eventos, tem de indicar a data/hora no campo eventTime no formato especificado pela RFC 3339.

Podem ser necessários outros campos consoante o método da API usado ou se forem usados campos adicionais. (Por exemplo, se o evento do utilizador estiver associado a uma entidade, certifique-se de que especifica o campo entity.) Para ver detalhes completos de cada campo e quando são obrigatórios, consulte a UserEvent documentação de referência da API.

Píxel de JavaScript

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

Gestor de Etiquetas 

<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 este tipo de evento de utilizador. Especifique este esquema quando criar tabelas para este tipo de evento do utilizador no BigQuery.

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

Tenha em atenção que o eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato 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

O exemplo seguinte mostra o formato dos dados de eventos do utilizador purchase-complete.

Os exemplos seguintes mostram apenas os campos obrigatórios do purchase-complete formato de evento do utilizador.

Quando importa eventos, tem de indicar a data/hora no campo eventTime no formato especificado pela RFC 3339.

Podem ser necessários outros campos consoante o método da API usado ou se forem usados campos adicionais. (Por exemplo, se o evento do utilizador estiver associado a uma entidade, certifique-se de que especifica o campo entity.) Para ver detalhes completos de cada campo e quando são obrigatórios, consulte a UserEvent documentação de referência da API.

Píxel de JavaScript

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

Gestor de Etiquetas 

<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 este tipo de evento de utilizador. Especifique este esquema quando criar tabelas para este tipo de evento do utilizador no BigQuery.

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

Tenha em atenção que o eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato 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"
 }
]

O exemplo seguinte mostra o formato do evento de utilizador search.

Objeto de pesquisa mínimo necessário

Estes são os campos mínimos obrigatórios para o Vertex AI Search for commerce devolver uma lista de resultados da pesquisa:

  • searchQuery é lido a partir do parâmetro search_term ou de eventos view_search_results.
  • productDetails é lido a partir do parâmetro items do evento view_item_list. Deve incluir a lista de IDs dos produtos apresentados ao utilizador final na página de resultados da pesquisa.
  • userEvents capta todas as informações de metadados que a Retail API precisa de saber sobre a forma como os utilizadores finais interagem com o Website do cliente.

Os exemplos seguintes mostram apenas os campos obrigatórios do formato de search evento de utilizador.

Quando importa eventos, tem de indicar a data/hora no campo eventTime no formato especificado pela RFC 3339.

Podem ser necessários outros campos consoante o método da API usado ou se forem usados campos adicionais. (Por exemplo, se o evento do utilizador estiver associado a uma entidade, certifique-se de que especifica o campo entity.) Para ver detalhes completos de cada campo e quando são obrigatórios, consulte a UserEvent documentação de referência da API.

Píxel de JavaScript

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

Gestor de Etiquetas 

<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 este tipo de evento de utilizador. Especifique este esquema quando criar tabelas para este tipo de evento do utilizador no BigQuery.

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

Tenha em atenção que o eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato 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

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

Os exemplos seguintes mostram o campo completionDetail quando um utilizador escreve "sh" e clica na segunda sugestão, "sapatos", na lista de sugestões para acionar um evento de pesquisa. Se o utilizador não clicar em nenhuma sugestão, o campo completionDetail permanece vazio.

eventType tem de ser "search".

completionAttributionToken é a attributionToken da resposta completeQuery.

selectedSuggestion deve ser igual a searchQuery.

Píxel de JavaScript

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

Gestor de Etiquetas 

<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 este tipo de evento de utilizador. Especifique este esquema quando criar tabelas para este tipo de evento do utilizador no BigQuery.

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

Tenha em atenção que o eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato 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

O exemplo seguinte mostra o formato dos dados de eventos do utilizador shopping-cart-page-view.

Os exemplos seguintes mostram apenas os campos obrigatórios do shopping-cart-page-view formato de evento do utilizador.

Forneça os objetos productDetails e userEvents, a menos que o carrinho de compras esteja vazio.

Quando importa eventos, tem de indicar a data/hora no campo eventTime no formato especificado pela RFC 3339.

Podem ser necessários outros campos consoante o método da API usado ou se forem usados campos adicionais. (Por exemplo, se o evento do utilizador estiver associado a uma entidade, certifique-se de que especifica o campo entity.) Para ver detalhes completos de cada campo e quando são obrigatórios, consulte a UserEvent documentação de referência da API.

Píxel de JavaScript

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, pela quantidade do produto, pelo ID da sessão e pelo ID do carrinho de compras.

Gestor de Etiquetas 

<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, pela quantidade do produto, pelo ID da sessão e pelo ID do carrinho de compras.

BigQuery

Este é o esquema JSON completo para este tipo de evento de utilizador. Especifique este esquema quando criar tabelas para este tipo de evento do utilizador no BigQuery.

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

Tenha em atenção que o eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato 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 de utilizador do Google Analytics 4

A tabela seguinte mostra como os campos de eventos de utilizador do Google Analytics 4 são mapeados para os campos do Vertex AI Search for commerce.

Antes de importar ou registar eventos de utilizadores do Google Analytics 4, certifique-se de que os eventos de utilizadores do Google Analytics 4 usam os seguintes campos para que a Pesquisa da Vertex AI para comércio possa integrar os seus dados corretamente.

Google Analytics 4 Retalho
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

O que se segue?