Esta é a documentação do Recommendations AI, da Pesquisa de varejo e do novo Console do Varejo. Para usar a pesquisa de varejo na fase GA restrita, entre em contato com a equipe de vendas do Cloud.

Se você estiver usando apenas o Recommendations AI, permaneça no Console do Recommendations e consulte a documentação do Recommendations AI.

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.

O Retail usa eventos do usuário em tempo real para gerar recomendações e resultados de pesquisa. Quando você faz o upload de dados para a API Retail, o Recommendations AI e a Pesquisa de varejo podem usá-los. Portanto, não é necessário fazer o upload dos mesmos eventos duas vezes se você usa os dois serviços.

Para ajuda com a gravação de eventos do usuário, consulte Como gravar 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 Recommendations AI)

search (para Pesquisa de varejo)
Importante para melhorar a qualidade do modelo do Recommendations AI 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 tipos de evento do usuário usados pelo Recommendations AI e pela Pesquisa de varejo. Verifique se os eventos do usuário atendem a esses requisitos para que a API Retail possa gerar resultados de qualidade.

Nesta seção estão listados:

Se você usa modelos do Recommendations AI, os requisitos de dados do evento do usuário listam outros requisitos dependendo do tipo de modelo de recomendação e do objetivo de otimização que você pretende usar.

Requisitos da API Retail

Verifique se os eventos do usuário atendem aos requisitos a seguir para que a API Retail possa gerar resultados de qualidade. Eles se aplicam ao Recommendations AI e à Pesquisa de varejo.

Tipo de evento Requisito Impacto
Todos os eventos

Não inclua eventos duplicados.

Eventos duplicados podem resultar em valores incorretos de métricas e afetar negativamente a qualidade do modelo.

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

Isso garante que a API Retail tenha dados suficientes para gerar resultados de qualidade.

O campo Product.name é obrigatório para todos os produtos. Use o nome completo do recurso do produto, não o ID do produto, que é o componente final do nome do recurso.

Um evento que inclui um produto sem campo Product.name não pode ser usado na API Retail.

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.

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.

Sem esse campo, os modelos de otimização de receita não estarão disponíveis.

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

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

Requisitos específicos do Recommendations AI

Se você estiver usando o Recommendations AI, verifique se os eventos do usuário atendem aos requisitos a seguir.

Se você usa modelos do Recommendations AI, os requisitos de dados do evento do usuário listam outros requisitos dependendo do tipo de modelo de recomendação e do objetivo de otimização que você pretende usar.

Tipo de evento Requisito Impacto
purchase

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 específicos da Pesquisa de varejo

Se você estiver usando a Pesquisa de varejo, verifique se os eventos de usuário atendem aos requisitos a seguir.

Tipo de evento Requisito Impacto
search

É necessário que search_query exista para eventos de pesquisa (exceto 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 API Retail 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 pesquisa afeta muito negativamente a qualidade da pesquisa e a precisão das métricas.

Requisitos dos objetivos de pesquisa

Diferentes objetivos de otimização têm diferentes dados e requisitos de volume de dados.

Confirme se é possível atender aos requisitos mínimos de dados para seu objetivo e trabalhe com a equipe de engenharia da Pesquisa de varejo para escolher um objetivo de otimização específico.

A janela de coleta de dados representa o período máximo em que a API Retail analisa os eventos do usuário.

Objetivo da otimização Tipos de evento do usuário Requisito de dados mínimos Janela de coleta de dados
Relevância

Opcional, mas altamente recomendado:

  • search
  • detail-page-view
  • add-to-cart
  • purchase-complete

 Não há requisito mínimo de dados explícitos para esse objetivo. A Pesquisa de varejo pode oferecer bons resultados sem eventos de usuário preexistentes. Entretanto, é altamente recomendável cumprir as diretrizes a seguir para melhorar a relevância dos resultados:
  • Os eventos search contêm a lista de produtos na ordem em que ela é exibida para o usuário final
  • Pelo menos sete dias de eventos de usuário para os tipos listados.
 7 dias
Taxa de cliques
  • search
  • detail-page-view
  • add-to-cart (opcional, mas altamente recomendado)
 Pelo menos 21 dias de eventos de usuário para os tipos obrigatórios
OU
(2.000.000 search eventos
E
500.000 eventos detail-page-view gerados de cliques da pesquisa)
E
100 produtos exclusivos de cliques de pesquisa
E
uma média de pelo menos 10 cliques de pesquisa por produto pesquisável.		 Três semanas ou até que o requisito mínimo de dados seja atendido
Taxa de conversão / Receita
  • search
  • detail-page-view
  • add-to-cart
  • purchase-complete
 Eventos search contêm a lista de produtos na ordem em que é exibida ao usuário final
E
(Pelo menos 28 dias de eventos de usuário do tipo obrigatório
OU
(4.000.000 eventos search
E
1.000.000 eventos detail-page-view gerados de cliques da pesquisa
E
uma média de pelo menos 0,5 eventos purchase-complete por produto pesquisável gerado das atividades de pesquisa.))		 Um mês ou até que o requisito mínimo de dados seja atendido

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 com a API Retail.

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.

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. Os eventos predict, search e detail-page-view gerados de cliques da API Retail precisam ter um token de atribuição para vincular os eventos às pesquisas ou recomendações que geraram.
  • Certifique-se de que todos os seus eventos usem uma única moeda, principalmente se você pretende usar o Console do Cloud para ver métricas de receita. A API Retail 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 Eventos do usuário.

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.

JavaScript Pixel

var user_event = {
  "eventType": "add-to-cart",
  "visitorId": "visitor-id",
  "cartId": "cart-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.
        'cartId': 'cart-id',
        '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": "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"
 }
]
}
]

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.

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": "pageCategories",
"type": "STRING",
"mode": "REPEATED"
}
]

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.

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": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
 {
   "name": "product",
   "type": "RECORD",
   "mode": "REQUIRED",
   "fields": [
     {
       "name": "id",
       "type": "STRING",
       "mode": "REQUIRED"
     }
   ]
 }
]
}
]

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.

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"
}
]

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.

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": "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": "purchaseTransaction",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
 {
   "name": "revenue",
   "type": "FLOAT",
   "mode": "REQUIRED"
 },
 {
   "name": "currencyCode",
   "type": "STRING",
   "mode": "REQUIRED"
 }
]
}
]

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.

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"
}
]

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.

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"
}
]

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 com o Recommendations AI. Para adicionar atributos personalizados, use attributes ao registrar um evento do usuário.

Forneça valores de texto personalizados usando o campo text ou valores numéricos personalizados 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ê registra um evento do usuário contêm o valor userId. userId é opcional e pode ser usado como um identificador permanente e exclusivo de um usuário em vários dispositivos sempre que um usuário fizer login no site. Quando você grava o userId de um usuário, a API Retail pode gerar resultados mais personalizados para um usuário em vários dispositivos, como dispositivos móveis 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 a API Retail armazenará os eventos na ordem correta. Os carimbos de data/hora são registrados automaticamente para eventos coletados usando o Gerenciador de tags e o JavaScript Pixel. Ao importar eventos, é necessário informar o carimbo de data/hora no campo eventTime no formato especificado pela RFC 3339.

A seguir