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.
Se precisar de ajuda com a gravação de eventos do usuário, consulte 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 |
|
Importante para melhorar a qualidade do modelo do Recommendations AI ao longo do tempo |
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:
- Requisitos da API Retail: requisitos gerais de eventos do usuário para a API Retail. Esses requisitos se aplicam ao Recommendations AI e à Pesquisa de varejo.
- Requisitos específicos do Recommendations AI: requisitos de eventos do usuário para o Recommendations AI.
- Requisitos específicos para a Pesquisa de varejo: requisitos de eventos do usuário para a Pesquisa de varejo.
Se você usa modelos do Recommendations AI, consulte também os Requisitos de dados do tipo de modelo, que listam outros requisitos dependendo do tipo de modelo de recomendação e do objetivo de otimização que você planeja usar.
É possível visualizar as métricas de qualidade de dados da Retail Search na página Qualidade de dados no Console do Retail. Essas métricas mostram as porcentagens de produtos e eventos de usuário que atendem aos padrões recomendados de qualidade de dados. Para informações sobre como conferir a qualidade dos dados de pesquisa, consulte Desbloquear níveis de desempenho da pesquisa.
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 dados sintéticos ou eventos duplicados. |
Eventos sintéticos ou duplicados prejudicam a qualidade do modelo e geralmente impedem um treinamento de modelo bem-sucedido. 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 API Retail tenha dados suficientes para gerar resultados de qualidade. |
|
Os IDs de visitantes precisam ser formatados da mesma forma na importação ou no registro de eventos e nas solicitações da API Retail. |
O uso de um formato consistente para IDs de visitantes ajuda a API Retail a identificar corretamente os padrões de visitantes e a 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. Dados de eventos não integrados não são usados para treinar modelos. No entanto, eventos desvinculados podem ser mesclados mais tarde, depois que os produtos associados forem ingeridos. Para mais informações, 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, o Retail precisa ter acesso a vários eventos com o mesmo ID de visitante.
Por exemplo, |
|
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 |
Eventos |
Inclua exatamente um Não há um código de moeda padrão. É necessário fornecer um código. |
Os eventos de compra sem esse campo resultam em métricas de receita incorretas. |
|
Confira se alguns eventos de compra incluem vários produtos. |
Ter alguns eventos de compra com vários produtos ajuda o modelo a aprender padrões de cocompra. |
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, consulte também os Requisitos de dados do tipo de modelo, que listam outros requisitos dependendo do tipo de modelo de recomendação e do objetivo de otimização que você planeja usar.
Tipo de evento | Requisito | Impacto |
---|---|---|
purchase-complete |
Não nivele cestas com vários itens em vários eventos de compra. Elas devem permanecer como eventos de compra únicos que incluem vários produtos. |
Isso garante que sejam gerados padrões de compra conjunta válidos. |
Requisitos da Retail Search
Se você estiver usando a Retail Search, verifique se os eventos de usuário atendem aos requisitos mínimos a seguir para receber resultados.
Tipo de evento | Requisito | Impacto |
---|---|---|
search |
|
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, |
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 |
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 Retail Search otimize automaticamente a experiência de pesquisa com base nas tendências gerais do usuário, faça o upload dos dados a seguir.
Os eventos precisam ser enviados pelo menos uma vez por dia com um atraso máximo de 24 horas.
Métrica "Eventos" | Volume/frequência de eventos | Descrição |
---|---|---|
Volume de search eventos |
2.000.000 nos últimos 90 dias |
Pelo menos 2 milhões de eventos nos últimos 90 dias são necessários para otimizar a experiência de pesquisa com base nos eventos ingeridos.
Recomendamos que você faça upload dos eventos pelo menos uma vez ao dia para manter a qualidade dos dados. Durante as importações de eventos históricos, verifique se a distribuição de dados se distorce em relação ao 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
evento search |
500.000 nos últimos 30 dias | Pelo menos 500.000 eventos são necessários para otimizar os resultados da pesquisa usando eventos do usuário. |
Média de eventos detail-page-view atribuíveis a um
evento search por produto |
10 nos últimos 30 dias | Obrigatório para otimizar os resultados da pesquisa usando os eventos ingeridos, a menos que você faça o upload dos 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 na resposta da pesquisa. |
Proporção de produtos pesquisados com preço | 0,95 nos últimos 30 dias | Obrigatório para otimizar os resultados da pesquisa usando os eventos ingeridos. |
Média de eventos add-to-cart que podem ser atribuídos a um
evento search por produto cobrado |
0,5 nos últimos 30 dias | Recomendado para resultados de pesquisa otimizados para receita. |
Média de eventos purchase-complete que podem ser 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 Retail Search exige os dados a seguir para personalizar a pesquisa de texto e navegar nos resultados da pesquisa para seus usuários com base na atividade deles.
Depois que você fizer upload dos dados a seguir, a Retail Search poderá personalizar os resultados automaticamente.
Métrica "Eventos" | Volume/frequência de eventos | Descrição |
---|---|---|
Volume de search eventos veiculados pela Retail Search |
100.000 nos últimos 30 dias |
Pelo menos 100.000 eventos veiculados pela Retail Search nos últimos 30 dias são necessários para oferecer personalização.
|
Os resultados da Pesquisa de varejo não são armazenados em cache | Menos de 1% dos 100 mil eventos de usuário mais recentes |
Não armazene em cache os resultados da Retail Search para pesquisa de texto ou navegação se você planeja usar a personalização. Reutilizar os mesmos resultados entre visitantes impede que a Retail Search forneça resultados realmente personalizados para qualquer usuário e corre o risco de expor os dados particulares deles. A Pesquisa de varejo vai desativar automaticamente a personalização se o armazenamento em cache for detectado. Se você armazenar somente os resultados da pesquisa em cache, a Retail Search ainda poderá personalizar esses resultados. Por outro lado, se você armazenar somente os resultados de navegação em cache, a Retail Search ainda poderá personalizar os resultados da pesquisa de consulta de texto. |
Correspondências de ID do visitante entre SearchRequests e eventos do usuário
|
Mais de 10% de correspondência para os 100.000 eventos de usuário mais recentes |
Verifique se o espaçamento e a formatação do ID do visitante correspondem entre
SearchRequests e eventos de usuário. A formatação consistente do ID de visitante
garante que a Retail Search possa identificar a atividade do usuário
corretamente.
|
Exemplos e esquemas de tipo de evento do usuário
Nesta seção, apresentamos os formatos de dados para cada tipo de evento compatível 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 eventospredict
,search
edetail-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. - Verifique se todos os eventos usam uma única moeda, especialmente se você planeja usar o Console do Google Cloud para conseguir 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 de usuário, consulte a
documentação de referência da API UserEvent
.
Adicionar ao carrinho
Veja a seguir o formato de evento do usuário add-to-cart
.
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, é preciso fornecer o carimbo de data/hora no campo eventTime
no formato especificado pela RFC 3339 (link em inglês).
Outros campos podem ser obrigatórios, dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a
uma entidade, especifique o campo entity
.
Para ver todos os detalhes de cada campo e quando eles são obrigatórios, consulte a
documentação de referência da API UserEvent
.
JavaScript Pixel
var user_event = { "eventType": "add-to-cart", "visitorId": "visitor-id", "productDetails": [{ "product": { "id": "product-id" }, "quantity": 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, é preciso fornecer o carimbo de data/hora no campo eventTime
no formato especificado pela RFC 3339 (link em inglês).
Outros campos podem ser obrigatórios, dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a
uma entidade, especifique o campo entity
.
Para ver todos os detalhes de cada campo e quando eles são obrigatórios, consulte a
documentação de referência da API UserEvent
.
JavaScript Pixel
var user_event = { "eventType": "category-page-view", "visitorId": "visitor-id", "pageCategories": ["category1 > category2"] };
Gerenciador de tags
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'category-page-view', 'visitorId": 'visitor-id', // You can also define the user ID and visitor ID // directly on the Tag Manager tag. 'pageCategories': ['category1 > category2'] } }); </script>
BigQuery
Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.
Os modos dos campos obrigatórios estão definidos como REQUIRED
ou REPEATED
. Os modos dos
campos opcionais são definidos como NULLABLE
.
Observe que eventTime
é necessário para importar eventos com o
BigQuery. eventTime
é uma string com 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, é preciso fornecer o carimbo de data/hora no campo eventTime
no formato especificado pela RFC 3339 (link em inglês).
Outros campos podem ser obrigatórios, dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a
uma entidade, especifique o campo entity
.
Para ver todos os detalhes de cada campo e quando eles são obrigatórios, consulte a
documentação de referência da API UserEvent
.
JavaScript Pixel
var user_event = { "eventType": "detail-page-view", "visitorId": "visitor-id", "productDetails": [{ "product": { "id": "product-id" } }] };
Gerenciador de tags
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'detail-page-view', 'visitorId': 'visitor-id', // You can also define the visitor ID directly on // the Tag Manager tag. 'productDetails': [{ 'product': { 'id': 'product-id' } }] } }); </script>
BigQuery
Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.
Os modos dos campos obrigatórios estão definidos como REQUIRED
ou REPEATED
. Os modos dos
campos opcionais são definidos como NULLABLE
.
Observe que eventTime
é necessário para importar eventos com o
BigQuery. eventTime
é uma string com 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, é preciso fornecer o carimbo de data/hora no campo eventTime
no formato especificado pela RFC 3339 (link em inglês).
Outros campos podem ser obrigatórios, dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a
uma entidade, especifique o campo entity
.
Para ver todos os detalhes de cada campo e quando eles são obrigatórios, consulte a
documentação de referência da API UserEvent
.
JavaScript Pixel
var user_event = { "eventType": "home-page-view", "visitorId": "visitor-id", };
Gerenciador de tags
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'home-page-view', 'visitorId': 'visitor-id' // You can also define the visitor ID // directly on the Tag Manager tag. } }); </script>
BigQuery
Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.
Os modos dos campos obrigatórios estão definidos como REQUIRED
ou REPEATED
. Os modos dos
campos opcionais são definidos como NULLABLE
.
Observe que eventTime
é necessário para importar eventos com o
BigQuery. eventTime
é uma string com 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, é preciso fornecer o carimbo de data/hora no campo eventTime
no formato especificado pela RFC 3339 (link em inglês).
Outros campos podem ser obrigatórios, dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a
uma entidade, especifique o campo entity
.
Para ver todos os detalhes de cada campo e quando eles são obrigatórios, consulte a
documentação de referência da API UserEvent
.
JavaScript Pixel
var user_event = { "eventType": "purchase-complete", "visitorId": "visitor-id", "productDetails": [{ "product": { "id": "product-id" }, "quantity": product-quantity }], "purchaseTransaction": { "revenue": revenue, "currencyCode": "currency-code" } };
Gerenciador de tags
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'purchase-complete', 'visitorId': 'visitor-id', // You can also define the visitor id directly on // the Tag Manager tag. 'productDetails': [{ 'product': { 'id': 'product-id' }, 'quantity': product-quantity }], 'purchaseTransaction': { 'revenue': revenue, 'currencyCode': 'currency-code' } } }); </script>
BigQuery
Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.
Os modos dos campos obrigatórios estão definidos como REQUIRED
ou REPEATED
. Os modos dos
campos opcionais são definidos como NULLABLE
.
Observe que eventTime
é necessário para importar eventos com o
BigQuery. eventTime
é uma string com 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" } ]
Pesquisa
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, é preciso fornecer o carimbo de data/hora no campo eventTime
no formato especificado pela RFC 3339 (link em inglês).
Outros campos podem ser obrigatórios, dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a
uma entidade, especifique o campo entity
.
Para ver todos os detalhes de cada campo e quando eles são obrigatórios, consulte a
documentação de referência da API UserEvent
.
JavaScript Pixel
var user_event = { "eventType": "search", "visitorId": "visitor-id", "searchQuery": "search-query", "pageCategories": ["category1 > category2"], "productDetails": [ { "product": { "id": "product-id1" } }, { "product": { "id": "product-id2" } } ] };
Gerenciador de tags
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'search', 'visitorId': 'visitor-id', // You can also define the visitor ID // directly on the Tag Manager tag. 'searchQuery': 'search-query', 'pageCategories': ['category1 > category2'], 'productDetails': [ { 'product': { 'id': 'product-id1' } }, { 'product': { 'id': 'product-id2' } } ] } }); </script>
BigQuery
Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.
Os modos dos campos obrigatórios estão definidos como REQUIRED
ou REPEATED
. Os modos dos
campos opcionais são definidos como NULLABLE
.
Observe que eventTime
é necessário para importar eventos com o
BigQuery. eventTime
é uma string com 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 o Autocomplete. Ele não é necessário para a pesquisa.
Os exemplos a seguir mostram o campo completionDetail
quando um usuário digita "sh"
e clica na segunda sugestão, "shoes", na lista de sugestões para acionar um
evento de pesquisa. Se o usuário não clicar em nenhuma sugestão, o campo completionDetail
vai permanecer vazio.
eventType
precisa ser "search"
.
completionAttributionToken
é o attributionToken
da resposta completeQuery
.
selectedSuggestion
precisa ser igual a searchQuery
.
JavaScript Pixel
var user_event = { "eventType": "search", "visitorId": "visitor-id", "searchQuery": "search-query", "pageCategories": ["category1 > category2"], "productDetails": [ { "product": { "id": "product-id1" } }, { "product": { "id": "product-id2" } } ] "completionDetail": { "completionAttributionToken": "completion_token", "selectedSuggestion": "search-query", "selectedPosition": completion_position } };
Gerenciador de tags
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'search', 'visitorId': 'visitor-id', // You can also define the visitor ID // directly on the Tag Manager tag. 'searchQuery': 'search-query', 'pageCategories': ['category1 > category2'], 'productDetails': [ { 'product': { 'id': 'product-id1' } }, { 'product': { 'id': 'product-id2' } } ] "completionDetail": { "completionAttributionToken": 'completion_token', "selectedSuggestion": 'search-query', "selectedPosition": completion_position } } }); </script>
BigQuery
Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.
Os modos dos campos obrigatórios estão definidos como REQUIRED
ou REPEATED
. Os modos dos
campos opcionais são definidos como NULLABLE
.
Observe que eventTime
é necessário para importar eventos com o
BigQuery. eventTime
é uma string com 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, é preciso fornecer o carimbo de data/hora no campo eventTime
no formato especificado pela RFC 3339 (link em inglês).
Outros campos podem ser obrigatórios, dependendo do método de API usado ou se campos adicionais forem usados. Por exemplo, se o evento do usuário estiver associado a
uma entidade, especifique o campo entity
.
Para ver todos os detalhes de cada campo e quando eles são obrigatórios, consulte a
documentação de referência da API UserEvent
.
JavaScript Pixel
var user_event = { "eventType": "shopping-cart-page-view", "visitorId": "visitor-id "cartId": "cart-id", "productDetails": [{ "product": { "id": "product-id" }, { "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" } ]
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 de usuário.
Se você fornecer atributos personalizados para eventos de usuário ingeridos, também é importante incluí-los nos eventos de usuário associados às solicitações de previsão. A formatação dos atributos personalizados precisa ser consistente entre eventos importados e fornecidos com solicitações de previsão. Isso permite que a API Retail use esses atributos personalizados ao treinar modelos e exibir previsões, o que ajuda a melhorar a qualidade da recomendação.
É possível fornecer 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
de 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 permanente para um usuário em vários dispositivos sempre que ele fizer login no seu site. Quando você registra o userId
para um usuário, a API
Varejo 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 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
- Saiba como gravar eventos do usuário.