Sobre os eventos de usuários de mídia

Esta página descreve os eventos do usuário para apps de pesquisa e recomendações de mídia, incluindo tipos, requisitos e exemplos de eventos do usuário. Os eventos do usuário são necessários para apps de mídia.

Para informações gerais sobre pesquisa e recomendações de mídia, consulte Introdução à pesquisa e recomendações de mídia.

Para ajuda com a gravação de eventos do usuário, consulte Registrar eventos do usuário em tempo real. Para importar eventos anteriores do usuário em massa, consulte Importar eventos históricos do usuário.

Tipos de evento do usuário

Você pode registrar os seguintes tipos de eventos de usuário conforme os usuários finais navegam ou pesquisam no seu site:

Nome do evento do usuário Ação do usuário
view-item Mostra os detalhes de um documento.
view-home-page Acessa a página inicial.
search Pesquisa no repositório de dados.
media-play Clica para reproduzir um item de mídia.
media-complete Interrompe a reprodução de um item de mídia, indicando o fim da visualização.

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

Requisitos de eventos para pesquisa e recomendações de mídia

Os tipos de eventos do usuário necessários são determinados de acordo com o objetivo (taxa de cliques, taxa de conversão ou duração da visualização), se o app é de pesquisa ou de recomendações e, apenas para apps de recomendações, pelo tipo de modelo escolhido. Para mais informações sobre tipos de modelos de recomendação e objetivos de otimização, consulte Sobre os tipos de recomendações de apps de mídia.

Para determinar quais eventos de usuário você precisa coletar, consulte a tabela a seguir.

Evento search view-home-page view-item media-play media-complete
Caso de uso de pesquisa
Obrigatório Não
obrigatório		 Obrigatório Obrigatório Obrigatório
Tipo de modelo "Recomendado para você", por objetivo
CTR Não
obrigatório		 Obrigatório para contexto da página inicial

Não obrigatório para contexto geral		 É necessário view-item ou media-play.
Recomendado

Obrigatório se a redução de classificação do histórico estiver ativada
CVR Não
obrigatório		 Obrigatório para contexto da página inicial

Não obrigatório para contexto geral		 É necessário view-item ou media-play. Obrigatório
Duração da exibição Não
obrigatório		 Obrigatório para contexto da página inicial

Não obrigatório para contexto geral		 É necessário view-item ou media-play. Obrigatório
Tipo de modelo "Outros itens que você pode gostar", por objetivo
CTR Não
obrigatório		 Não
obrigatório		 É necessário view-item ou media-play.
Altamente recomendado

Obrigatório se a redução de classificação do histórico estiver ativada
CVR Não
obrigatório		 Não
obrigatório		 É necessário view-item ou media-play. Obrigatório
Duração da exibição Não
obrigatório		 Não
obrigatório		 É necessário view-item ou media-play. Obrigatório
Tipo de modelo "Mais como isto", por objetivo
CTR Não
obrigatório		 Não
obrigatório		 É necessário view-item ou media-play. Obrigatório se a redução de classificação do histórico estiver ativada
CVR Não
obrigatório		 Não
obrigatório		 É necessário view-item ou media-play. Obrigatório
Duração da exibição Não
obrigatório		 Não
obrigatório		 É necessário view-item ou media-play. Obrigatório
Tipo de modelo mais usado, por objetivo
CTR Não
obrigatório		 Não
obrigatório		 É preciso especificar view-item ou media-play. Não
obrigatório
CVR Não
obrigatório		 Não
obrigatório		 Não
obrigatório		 Não
obrigatório		 Obrigatório

Requisitos para eventos do usuário de mídia

Verifique se os eventos do usuário atendem aos requisitos a seguir para que seus apps de mídia possam gerar resultados de qualidade.

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 dos resultados e podem impedir a implantação do app. Eventos duplicados podem causar valores incorretos de métricas.

Inclua pelo menos 100 IDs pseudônimos de usuários únicos para cada tipo de evento processado.

Inclua esses IDs para que os apps de recomendações de mídia tenham dados suficientes para gerar resultados de qualidade.

Os pseudo IDs de usuário precisam ser formatados exatamente da mesma forma na importação ou gravação de eventos e nas solicitações de recomendações de mídia.

Usar um formato consistente para pseudônimos de usuários ajuda os apps de recomendação de mídia a identificar corretamente os padrões de visitantes e oferecer resultados de melhor qualidade com base no comportamento do usuário.

O campo DocumentInfo.name ou DocumentInfo.id é obrigatório para todos os documentos.

Um evento que inclui um documento sem um campo DocumentInfo.name ou DocumentInfo.id não pode ser usado por apps de recomendações de mídia.

Os documentos incluídos nos eventos precisam estar no seu repositório de dados.

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

Alguns eventos de usuário precisam ter o mesmo ID pseudônimo do usuário.

Para criar históricos de sequência de comportamento válidos, os apps de recomendações de mídia precisam conseguir ver vários eventos com o mesmo ID pseudônimo do usuário.

Por exemplo, visitor123 visualizou cinco itens e clicou em "Reproduzir" em dois deles. Se esses eventos fornecerem o mesmo ID pseudônimo do usuário formatado de maneira consistente, um app de recomendações de mídia poderá considerar essa sequência de comportamento nos resultados.

view-item

Inclua exatamente um documento por evento.

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

search

Inclua o attributionToken. O attributionToken é retornado pelo método search junto com os resultados da pesquisa ou navegação.

O attributionToken permite que a Vertex AI para Pesquisa atribua com precisão o evento de pesquisa a uma resposta de pesquisa específica.

media-play

Inclua exatamente um documento por evento.

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

Tags de evento do usuário para testes A/B

Se você fizer testes A/B, adicione IDs de tag a todos os eventos do usuário que você coleta, adicionando uma tag para cada grupo de teste.

Por exemplo, adicione a tag "tagIds": ["original"] aos eventos do usuário do seu modelo atual e a tag "tagIds": ["google"] aos eventos do usuário da Vertex AI para Pesquisa de mídia.

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 as recomendações de mídia. São fornecidos exemplos do JavaScript Pixel. Para o BigQuery, é fornecido o esquema de tabela completo para cada tipo.

Para todos os tipos de eventos do usuário, userId é opcional.

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

view-item

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

Objeto view-item mínimo necessário

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

Na maioria dos casos, documents contém detalhes do documento associado.

JavaScript Pixel

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "id": "document-id"
  }]
  "panels": [
     {
       "panelId": "HOME_RFY_1",
       "documents": [
         {
           "id": "123"
         },
         {
           "id": "456"
         }
       ],
       "panelPosition": 1,
       "totalPanels": 2
     }
  ]
};

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": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

view-home-page

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

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

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

JavaScript Pixel

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "panels": [
     {
       "panelId": "HOME_RFY_1",
       "documents": [
         {
           "id": "123"
         },
         {
           "id": "456"
         }
       ],
       "panelPosition": 1,
       "totalPanels": 2
     }
  ]
};

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": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "quantity",
        "type": "INT64",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

Para informações sobre o objeto panels, consulte Sobre os painéis.

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.

Forneça searchQuery para eventos de pesquisa em que o usuário inseriu uma consulta de texto.

O attributionToken é retornado com os resultados da consulta de pesquisa.

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

JavaScript Pixel

var user_event = {
  eventType: "search",
  userPseudoId: "user-pseudo-id",
  eventTime: "2020-01-01T03:33:33.000001Z",
  searchInfo: {
    searchQuery: "search-query",
  }, 
  attributionToken: "attribution-token",
  documents: [
    {
      id: "document-id1",
    },
    {
      id: "document-id2",
    },
  ]
};

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": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "searchInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "searchQuery",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageCategory",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

media-play

Veja a seguir o formato de evento do usuário media-play.

Objeto media-play mínimo necessário

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

JavaScript Pixel

var user_event = {
  "eventType": "media-play",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [
    {
      "id": "document-id1"
    }
  ]
};

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": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

media-complete

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

Objeto media-complete mínimo necessário

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

JavaScript Pixel

var user_event = {
  "eventType": "media-complete",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [
    {
      "id": "document-id1"
    }
  ],
  "mediaInfo": {
    "mediaProgressDuration": "65s",
    "mediaProgressPercentage": 0.2
  }
};

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": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  },
  {
    "name": "mediaInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "mediaProgressDuration",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "mediaProgressPercentage",
        "type": "NUMERIC",
        "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. Para adicionar atributos personalizados, use attributes ao registrar um evento do usuário.

Se você fornecer atributos personalizados para eventos do usuário ingeridos, é importante incluí-los também nos eventos do usuário associados a solicitações de recomendação e pesquisa. A formatação dos atributos personalizados precisa ser consistente entre eventos importados e eventos fornecidos com solicitações. Isso permite que apps de mídia usem esses atributos personalizados para melhorar a qualidade.

Forneça valores de texto personalizados usando o campo text ou valores numéricos personalizados usando o campo numbers.

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"]},
    user_zip: {numbers: [90210]}
  }

Sobre as informações do usuário

userPseudoId 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 userPseudoId e, se disponível, 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 ele faz login no site. Quando você grava o userId de um usuário, os apps de pesquisa e recomendações de mídia podem 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 os eventos sejam armazenados na ordem correta. Os carimbos de data/hora são registrados automaticamente para eventos coletados usando o JavaScript Pixel. Ao importar eventos, é necessário informar o carimbo de data/hora no campo eventTime no formato especificado pela RFC 3339.

Sobre os painéis

Em uma página inicial, geralmente há um ou mais painéis, como "Em alta agora" e "Recomendado para você". Nas páginas de detalhes, também podem aparecer painéis, como "Outros vídeos que você pode gostar".

Informações do painel para eventos do usuário

As informações do painel são necessárias para eventos do usuário de recomendação do tipo view-home-page e view-item. As informações do painel são obrigatórias para páginas iniciais e de detalhes que mostram conteúdo recomendado pelo Google.

Se você estiver fazendo um teste A/B para um painel, registre os eventos do usuário com informações do painel para todo o conteúdo do teste, independente da origem. Para páginas iniciais e de detalhes sem conteúdo de painel gerado pelo Google, é recomendável, mas não obrigatório, fornecer informações do painel nos eventos view-home-page e view-item. Esses requisitos estão resumidos na tabela a seguir:

Origem do evento do usuário (view-home-page e view-item) PanelInfo: obrigatório
Inclui conteúdo recomendado pelo Google Sim
Inclui conteúdo NÃO recomendado pelo Google e usado em testes A/B Sim
Inclui conteúdo NÃO recomendado pelo Google e NÃO usado em testes A/B Não

As informações do painel (PanelInfo) são um conjunto de campos que descrevem vários elementos do painel:

  • O número do ID do painel

  • O nome de exibição

  • A posição do painel na página (por exemplo, o primeiro painel (1) na página ou o terceiro painel (3) na página)

  • O número total de painéis na página

  • A lista de documentos (DocumentInfo) apresentada em cada painel

Para informações detalhadas sobre os objetos PanelInfo, consulte PanelInfo.

Pré-carregar painéis x carregar painéis de forma lenta

Há dois métodos comuns para mostrar recomendações em páginas da Web ou para dispositivos móveis. O método usado determina o número e o conteúdo dos eventos de usuário view-home-page que você registra.

  • Pré-carregamento:com o pré-carregamento, todos os itens de recomendação são gerados quando o usuário chega à página. Nesse caso, quando o usuário carrega a página inicial, você registra um evento de usuário view-home-page (ou view-item) com todos os painéis e documentos.

  • Carregamento lento:com o carregamento lento, o conteúdo do painel não é gerado quando o usuário chega à página. Em vez disso, o conteúdo é carregado dinamicamente quando o usuário rola para baixo até os painéis ou para a direita para ver mais recomendações. Nesse caso, quando um usuário carrega a página inicial, você registra um evento inicial do usuário view-home-page (ou view-item) e continua registrando mais eventos quando o usuário rola a tela para gerar mais conteúdo recomendado. Nos eventos subsequentes, você só precisa incluir na matriz panels o incremento de documentos exibidos.

Exemplo de cenário

A página inicial de uma empresa de mídia mostra dois painéis de recomendações:

  • Um painel de tendências que usa o modelo Mais procurados.

  • Um painel de recomendações personalizadas que está sendo testado com A/B. Alguns usuários veem um painel de sugestões gerado pelo modelo Recomendado para você (grupo A), e outros veem recomendações do modelo proprietário da empresa (grupo B).

Quando um usuário atribuído ao grupo B acessa essa página inicial, o evento do usuário no formato de pixel JavaScript fica assim:

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "4003345673.123451357",
  "eventTime": "2025-07-01T03:33:33.000001Z",
  "userInfo": {
    "userId": "jane.doe@example.com",
  },
  "tagIds": ["group-B"],
  "panels": [
    {
      "panelId": "panel-1",
      "displayId": "Trending Now",
      "documents": [
        {
          "id": "254722"
        },
        {
          "id": "2951"
        },
        ...
        {
          "id": "1201"
        }
      ],
      "panelPosition": 1,
      "totalPanels": 2
    },
    {
      "panelId": "panel-2",
      "displayId": "Recommended for You",
      "documents": [
        {
          "id": "79132"
        },
        {
          "id": "109487"
        },
        ...
        {
          "id": "164179"
        }
      ],
      "panelPosition": 2,
      "totalPanels": 2
    }
  ]
};

A seguir