Sobre eventos do usuário para apps personalizados

Nesta página, descrevemos os eventos de usuário para apps de pesquisa e recomendação personalizados, incluindo tipos de eventos de usuário, requisitos e exemplos de tipos de eventos de usuário.

Embora os eventos de usuário não sejam obrigatórios para apps personalizados, eles são altamente recomendados.

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

Para ajuda com a gravação de eventos do usuário, consulte [Gravar eventos do usuário em tempo real][record-events]. Para importar eventos de usuário anteriores em massa, consulte [Importar eventos históricos de usuários][import-user-events].

Tipos de evento do usuário

É possível 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-list Visualiza um painel ou uma lista ordenada de documentos.
view-item Visualiza detalhes de um documento.
view-home-page Visualiza a página inicial.
search Pesquisa no app.

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

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 apps personalizados. 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.

Observação:

  • O campo tagIds é necessário somente se você estiver executando um experimento A/B.

  • O campo attributionToken é opcional. Ele é usado para avaliar o desempenho. Os eventos search e view-item gerados por cliques de recomendações precisam ter um token de atribuição para vincular os eventos às recomendações que os geraram.

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

view-item

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

Requisitos de otimização de pesquisa para eventos view-item

Para que a pesquisa otimize automaticamente a experiência de pesquisa com base nas tendências gerais do usuário, faça upload dos seguintes dados.

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 eventos view-item 250 mil itens de visualização

Pelo menos 250.000 itens de visualização são necessários para otimizar a experiência de pesquisa com base nos eventos ingeridos.

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.

O documents objeto contém o ID do documento (id) e o nome do recurso (name).

  • Ao ingerir ou registrar eventos de usuário no nível do repositório de dados, é possível fornecer o ID (id) ou o nome do recurso (name) do documento.
  • Ao ingerir ou registrar eventos no nível do local, é necessário fornecer o nome do recurso (name) do documento, porque ele indica o caminho completo de um documento e se refere ao repositório de dados em que o documento reside. É possível fornecer o ID do documento como uma informação adicional opcional.

JavaScript Pixel

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "name": "DOCUMENT_NAME"
  }]
};

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": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "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.

O documents objeto contém o ID do documento (id) e o nome do recurso (name).

  • Ao ingerir ou registrar eventos de usuário no nível do repositório de dados, é possível fornecer o ID (id) ou o nome do recurso (name) do documento.
  • Ao ingerir ou registrar eventos no nível do local, é necessário fornecer o nome do recurso (name) do documento, porque ele indica o caminho completo de um documento e se refere ao repositório de dados em que o documento reside. É possível fornecer o ID do documento como uma informação adicional opcional.

JavaScript Pixel

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
};

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": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "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"
          }
        ]
      }
    ]
  }
]

Veja a seguir o formato de evento do usuário search.

Requisitos de otimização de pesquisa para eventos de pesquisa

Para que a pesquisa otimize automaticamente a experiência de pesquisa com base nas tendências gerais do usuário, faça upload dos seguintes dados.

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 eventos search 100 mil pesquisas

Pelo menos 100.000 pesquisas são necessárias para otimizar a experiência de pesquisa com base nos eventos ingeridos.

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.

É necessário incluir pelo menos um dos campos searchQuery ou pageCategory:

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

  • Forneça pageCategory quando o usuário navegar até os itens de interesse, ou seja, clicando em categorias em vez de inserir uma consulta de texto.

O attributionToken é retornado com a consulta de pesquisa ou os resultados de navegação.

O documents objeto contém o ID do documento (id) e o nome do recurso (name).

  • Ao ingerir ou registrar eventos de usuário no nível do repositório de dados, é possível fornecer o ID (id) ou o nome do recurso (name) do documento.
  • Ao ingerir ou registrar eventos no nível do local, é necessário fornecer o nome do recurso (name) do documento, porque ele indica o caminho completo de um documento e se refere ao repositório de dados em que o documento reside. É possível fornecer o ID do documento como uma informação adicional opcional.

JavaScript Pixel

var user_event = {
  "eventType": "search",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "searchInfo": {
    "searchQuery": "SEARCH_QUERY",
  }, 
  "pageInfo": {
    "pageCategory": "CATEGORY_1 > CATEGORY_2",
  }, 
  "attributionToken": "ATTRIBUTION_TOKEN",
  "documents": [
    {
      "name": "DOCUMENT_NAME_1",
    },
    {
      "name": "DOCUMENT_NAME_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": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "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"
      }
    ]
  }
]

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][user-info]) 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 um usuário fizer login no site. Quando você registra o userId de um usuário, os apps de pesquisa e recomendação 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][event-time] no formato especificado pela RFC 3339.

A seguir

  • Saiba como [gravar eventos do usuário][record-events].

[rec-type-reqs]: /generative-ai-app-builder/docs/about-media-recommendations-types [record-events]: /generative-ai-app-builder/docs/record-user-events [event-time]: /generative-ai-app-builder/docs/reference/rest/v1/projects.locations.dataStores.userEvents#UserEvent.FIELDS.event_time [user-event]: /generative-ai-app-builder/docs/reference/rest/v1/projects.locations.dataStores.userEvents [user-info]: /generative-ai-app-builder/docs/reference/rest/v1/projects.locations.dataStores.userEvents#userinfo

[import-user-events]: /generative-ai-app-builder/docs/import-user-events [record-events]: /generative-ai-app-builder/docs/record-user-events