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 para Retail usa eventos do usuário em tempo real para gerar recomendações e resultados da pesquisa. Quando você faz o upload de dados, as recomendações e a pesquisa conseguem usar isso Assim, você não precisa fazer o upload dos mesmos eventos duas vezes caso use os dois serviços.

Para receber ajuda com o registro de eventos do usuário, consulte Registre eventos do usuário em tempo real.

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
add-to-cart Adiciona o produto ao carrinho.
category-page-view Exibe páginas especiais, como páginas de promoção.
detail-page-view Exibe a página de detalhes do produto.
home-page-view Exibe a página inicial.
purchase-complete Conclui a finalização da compra.
search Pesquisa no catálogo.
shopping-cart-page-view Exibe o carrinho de compras.

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 Eventos do usuário
Obrigatório para experimento dinâmico inicial

add-to-cart

detail-page-view

purchase-complete

home-page-view (para recomendações)

search (para pesquisa)
Importante para melhorar a qualidade do modelo de recomendações ao longo do tempo

category-page-view

search

shopping-cart-page-view

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

As tabelas a seguir listam os requisitos e as práticas recomendadas para os tipos de evento do usuário usadas pelas recomendações e pesquisas. Verifique se os eventos do usuário atendam a esses requisitos para que a Vertex AI para Pesquisa para Retail podem gerar resultados de qualidade.

Nesta seção estão listados:

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

Você pode visualizar as métricas de qualidade de dados para pesquisa no Página Qualidade de dados na Pesquise o console de varejo. Essas métricas mostram porcentagens de produtos e eventos de usuário que atendem aos padrões recomendados de a qualidade dos dados. Para informações sobre como visualizar a qualidade dos dados de pesquisa, consulte Desbloquear níveis de desempenho de pesquisa.

Requisitos para eventos do usuário

Verifique se os eventos do usuário atendem aos requisitos a seguir para que os A Vertex AI para Pesquisa para Retail pode 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 dele. Eventos duplicados podem gerar valores de métricas incorretos.

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

Isso garante que a Vertex AI para Pesquisa para Retail tenha dados suficientes para gerar resultados de qualidade.

Os IDs de visitantes precisam ser formatados exatamente da mesma forma em toda a importação de eventos ou gravação de eventos e em solicitações de API.

Usar um formato consistente para IDs de visitante ajuda identificar corretamente os padrões de visitantes e fornecer 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 mesclados não são usados para treinar modelos. No entanto, os membros eventos podem ser combinados mais tarde, depois que os produtos associados forem ingeridos. Para saber mais, consulte Reintegrar eventos de 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 para Pesquisa para Retail precisa ver vários eventos com o mesmo ID de visitante.

Por exemplo, visitor123 visualizou cinco detalhes do produto de produtos, adicionaram três produtos ao carrinho e compraram dois dos cinco produtos originais. Se todos esses eventos fornecerem o mesmo ID com um formato consistente, a Vertex AI para Pesquisa para Retail pode 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.

purchase-complete evento sem o O campo revenue não é usado para treinar modelos.

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

Não há código de moeda padrão. um código deve ser fornecido.

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 os padrões de compra conjunta.

Requisitos específicos para recomendações

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

Se você usar modelos de recomendação, consulte também Requisitos de dados do tipo de modelo, que lista os requisitos adicionais 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 garante que sejam gerados padrões de compra conjunta válidos.

Requisitos de pesquisa

Se você estiver usando a pesquisa, verifique se os eventos de usuário atendem aos os requisitos mínimos a seguir para obter resultados. Os modelos da Vertex AI para Pesquisa para varejo só podem aprender a produzir melhores resultados de pesquisa para otimização da receita com base em eventos do usuário da pesquisa que são acompanhados por pelo menos uma interação do usuário. Uma interação do usuário ocorre sempre que um resultado de pesquisa é clicado, adicionado ao carrinho ou comprado.

Tipo de evento Requisito Impacto
search

searchQuery precisa existir para eventos de pesquisa. 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 Retail não poderá use a parte de filtro dos dados, o que pode afetar negativamente a pesquisa na qualidade dos resultados.

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

Não incluir um token de pesquisa afeta 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 o upload dos dados a seguir.

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 search eventos 2.500.000 nos últimos 90 dias

Pelo menos 2,5 milhões de eventos nos últimos 90 dias são necessários para otimizar a experiência de pesquisa com base em eventos ingeridos.

Recomendamos fazer upload de eventos pelo menos uma vez por dia para manter a boa qualidade dos dados. Durante as importações de eventos históricos, verifique se a distribuição de dados está no carimbo de data/hora mais recente. O número de eventos no último dia do carimbo de data/hora precisa ser igual ou maior que a média de eventos diários.

Volume de detail-page-view atribuível a um search evento 500.000 nos últimos 30 dias Pelo menos 500.000 eventos são necessários para otimizar a pesquisa usando eventos do usuário.
Média de eventos de detail-page-view atribuídos a um search evento por produto 10 nos últimos 30 dias Obrigatório para otimizar os resultados da pesquisa usando os eventos ingerido, a menos que seja feito o upload de eventos dos últimos 21 dias.
Proporção de eventos search com filtros analisáveis 0,1 nos últimos 30 dias Recomendado para otimizar a ordem dos atributos dinâmicos em a resposta da pesquisa.
Proporção dos 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 de add-to-cart atribuídos a um search evento por produto pago 0,5 nos últimos 30 dias Recomendado para resultados de pesquisa otimizados para receita.
Média de eventos de purchase-complete atribuídos a um Evento search por produto com preço pesquisável 0,5 nos últimos 30 dias Recomendado para resultados de pesquisa otimizados para receita.

Requisitos de personalização da Pesquisa

A pesquisa exige os seguintes dados para personalizar a pesquisa de texto e navegue pelos resultados da pesquisa para seus usuários com base nas atividades deles.

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

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

Pelo menos 100.000 eventos veiculados pela pesquisa nos últimos 30 dias.

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

Não armazene os resultados de pesquisa em cache para pesquisa ou navegação de texto pesquisas se planeja usar a personalização. Reutilizar os mesmos resultados entre visitantes impede que a Rede de Pesquisa forneça resultados personalizados para qualquer usuário e os riscos que expõem os usuários dados privados. A pesquisa é desativada automaticamente personalização se o armazenamento em cache for detectado.

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

Correspondências de ID de visitante entre SearchRequests e eventos do usuário Mais de 10% de correspondência com os 100.000 eventos de usuário mais recentes Verifique se o espaçamento e a formatação do ID de visitante correspondem SearchRequests e eventos do usuário. ID de visitante consistente a formatação garante que a pesquisa identifique a atividade do usuário corretamente.

Exemplos e esquemas de tipo de evento do usuário

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

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. As informações do produto campos (priceInfo e availability) são opcional.

Observações:

  • O campo experimentIds é necessário somente se você estiver executando um experimento A/B.
  • O campo attributionToken é opcional. Ele é usado para avaliar o desempenho. predict, search e detail-page-view eventos gerados a partir de cliques devem ter token de atribuição para vincular os eventos de volta às pesquisas ou e recomendações que as geraram.
  • Verifique se todos os seus eventos usam uma única moeda, especialmente se você planeja usá-la Console do Google Cloud para acessar métricas de receita. A API Vertex AI para Pesquisa para Retail não é compatível com o uso várias moedas por catálogo.

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

Adicionar ao carrinho

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

Objeto add-to-cart mínimo necessário

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

Ao importar eventos, você precisa fornecer o carimbo de data/hora no eventTime no formato especificado por RFC 3339.

Outros campos podem ser necessários dependendo do método de API usado ou se campos adicionais são usados. Por exemplo, se o evento de usuário estiver associado a uma entidade, não se esqueça de especificar o campo entity. Para conferir os detalhes completos 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": 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 o 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.

Objeto category-page-view mínimo necessário

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, você precisa fornecer o carimbo de data/hora no eventTime no formato especificado por RFC 3339.

Outros campos podem ser necessários dependendo do método de API usado ou se campos adicionais são usados. Por exemplo, se o evento de usuário estiver associado a uma entidade, não se esqueça de especificar o campo entity. Para conferir os detalhes completos 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 o 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.

Objeto detail-page-view mínimo necessário

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, você precisa fornecer o carimbo de data/hora no eventTime no formato especificado por RFC 3339.

Outros campos podem ser necessários dependendo do método de API usado ou se campos adicionais são usados. Por exemplo, se o evento de usuário estiver associado a uma entidade, não se esqueça de especificar o campo entity. Para conferir os detalhes completos 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 o 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.

Objeto home-page-view mínimo necessário

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

Ao importar eventos, você precisa fornecer o carimbo de data/hora no eventTime no formato especificado por RFC 3339.

Outros campos podem ser necessários dependendo do método de API usado ou se campos adicionais são usados. Por exemplo, se o evento de usuário estiver associado a uma entidade, não se esqueça de especificar o campo entity. Para conferir os detalhes completos 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 o 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.

Objeto purchase-complete mínimo necessário

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

Ao importar eventos, você precisa fornecer o carimbo de data/hora no eventTime no formato especificado por RFC 3339.

Outros campos podem ser necessários dependendo do método de API usado ou se campos adicionais são usados. Por exemplo, se o evento de usuário estiver associado a uma entidade, não se esqueça de especificar o campo entity. Para conferir os detalhes completos 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 o 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

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

Pelo menos um dos campos searchQuery ou pageCategories é obrigatório.

productDetails precisa incluir a lista de IDs de produto mostrados ao usuário final na página de resultados da pesquisa.

Ao importar eventos, você precisa fornecer o carimbo de data/hora no eventTime no formato especificado por RFC 3339.

Outros campos podem ser necessários dependendo do método de API usado ou se campos adicionais são usados. Por exemplo, se o evento de usuário estiver associado a uma entidade, não se esqueça de especificar o campo entity. Para conferir os detalhes completos 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 o 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ó será obrigatório para eventos de pesquisa se você quiser usar Preenchimento automático. Ele não é obrigatório para a pesquisa.

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

eventType precisa ser "search".

completionAttributionToken é o valor 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 o 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.

Objeto shopping-cart-page-view mínimo necessário

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

Forneça o objeto productDetails, exceto se o carrinho de compras estiver vazio.

Ao importar eventos, você precisa fornecer o carimbo de data/hora no eventTime no formato especificado por RFC 3339.

Outros campos podem ser necessários dependendo do método de API usado ou se campos adicionais são usados. Por exemplo, se o evento de usuário estiver associado a uma entidade, não se esqueça de especificar o campo entity. Para conferir os detalhes completos 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"
     },
     {
       "id": "product-id"
     }
   }]
};

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'
           },
           {
             '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 o 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 aos campos da Vertex AI para Pesquisa para Retail.

Antes de importar ou registrar eventos de usuário do Google Analytics 4, faça Verifique se os eventos de usuário do Google Analytics 4 usam os seguintes campos para que a Vertex AI para Pesquisa para Retail 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

Atributos personalizados

É possível incluir outros atributos e recursos personalizados para eventos do usuário. Isso pode resultar em recomendações melhores e mais específicas para seus usuários quando você use as recomendações. Para adicionar atributos personalizados, use attributes quando você grava um evento do usuário.

Se você fornecer atributos personalizados para eventos de usuário ingeridos, é importante incluí-las também nos eventos de usuário associados às previsões. solicitações. A formatação dos atributos personalizados precisa ser consistente entre e eventos importados fornecidos com solicitações de previsão. Isso permite o uso desses atributos personalizados ao treinar modelos e disponibilizar previsões, o que ajuda a melhorar a qualidade da recomendação.

É possível fornecer valores de texto personalizados usando o campo text ou personalizar valores numéricos usando o campo number.

Por exemplo, a seguir é mostrada a seção attributes de uma solicitação para gravar um evento do usuário:

"attributes": {
  "user_age": {"text": ["teen", "young adult"]},
  "user_location": {"text": ["CA"]}
}

Sobre as informações do usuário

visitorId representa o identificador de usuário único e é necessário para registrar um evento do usuário.

As informações do usuário (UserInfo) incluídas quando você grava um usuário contém o valor visitorId e, se disponível, o valor userId. userId é opcional e pode ser usado como um identificador exclusivo e persistente de um usuário em todos os dispositivos sempre que ele faz login em seu site. Quando você registra o userId para um usuário, a Vertex AI para Pesquisa para Retail pode gerar resultados mais personalizados para um usuário em vários dispositivos, como um dispositivo móvel e um navegador da Web.

Sobre o carimbo de data/hora

Ao registrar um evento do usuário, inclua um carimbo de data/hora preciso de quando o evento ocorreu. Carimbos de data/hora precisos garantem que os eventos sejam armazenados no na ordem correta. Os carimbos de data/hora são registrados automaticamente para eventos coletados usando do Gerenciador de tags e do pixel do JavaScript. Ao importar eventos, é necessário informar o carimbo de data/hora no campo eventTime no formato especificado pela RFC 3339.

A seguir