Acerca dos eventos do utilizador

Esta página descreve os eventos do utilizador para as apps Gemini Enterprise, incluindo tipos de eventos do utilizador, requisitos e exemplos de tipos de eventos do utilizador.

Se usar as APIs Gemini Enterprise nas suas próprias apps, tem de configurar a pesquisa na sua app para obter os eventos do utilizador e, em seguida, adicionar os dados dos eventos do utilizador à sua app Gemini Enterprise.

Se criar a sua app através da Google Cloud consola, não tem de importar manualmente eventos do utilizador (e não tem de ler esta página).

Para obter ajuda com o registo de eventos do utilizador, consulte o artigo Registe eventos do utilizador em tempo real. Para importar eventos de utilizadores anteriores em massa, consulte o artigo Importe eventos de utilizadores históricos.

Tipos de eventos do utilizador

Pode registar os seguintes tipos de eventos do utilizador à medida que os utilizadores finais navegam ou pesquisam no seu site:

Nome do evento do utilizador Ação do utilizador
view-item Ver detalhes de um documento.
search Pesquisa dados na app Gemini Enterprise.

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

Exemplos e esquemas de tipos de eventos de utilizadores

Esta secção fornece os formatos de dados para cada tipo de evento suportado pelas apps Gemini Enterprise. São facultados exemplos do Pixel de JavaScript. Para o BigQuery, é fornecido o esquema completo da tabela para cada tipo.

Para todos os tipos de eventos de utilizador, userId é opcional.

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

view_item

O exemplo seguinte mostra o formato dos dados de eventos do utilizador view-item.

Objeto view_item mínimo necessário

Os exemplos seguintes mostram apenas os campos obrigatórios do view-item formato de evento do utilizador.

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

Píxel de JavaScript

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

BigQuery

Este é o esquema JSON completo para este tipo de evento de utilizador. Especifique este esquema quando criar tabelas para este tipo de evento do utilizador no BigQuery.

Os modos dos campos obrigatórios estão definidos como REQUIRED ou REPEATED. Os modos dos campos opcionais estão definidos como NULLABLE.

Tenha em atenção que o eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato 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"
          }
        ]
      }
    ]
  }
]

O exemplo seguinte mostra o formato do evento de utilizador search.

Objeto de pesquisa mínimo necessário

Os exemplos seguintes mostram apenas os campos obrigatórios do formato de search evento de utilizador.

Forneça searchQuery para eventos de pesquisa em que o utilizador introduziu uma consulta de texto.

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

documents deve incluir a lista de IDs dos documentos apresentados ao utilizador final na página de resultados da pesquisa.

Píxel de JavaScript

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 este tipo de evento de utilizador. Especifique este esquema quando criar tabelas para este tipo de evento do utilizador no BigQuery.

Os modos dos campos obrigatórios estão definidos como REQUIRED ou REPEATED. Os modos dos campos opcionais estão definidos como NULLABLE.

Tenha em atenção que o eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato 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"
      }
    ]
  }
]

Acerca das informações do utilizador

userPseudoId representa o identificador único do utilizador e é obrigatório quando regista um evento do utilizador.

As informações do utilizador (UserInfo) incluídas quando regista um evento de utilizador contêm o valor userPseudoId e, se disponível, o valor userId. userId é opcional e pode ser usado como um identificador único e persistente de um utilizador em vários dispositivos sempre que um utilizador inicia sessão no seu site. Quando regista o userId para um utilizador, as apps Gemini Enterprise podem gerar resultados mais personalizados para um utilizador em vários dispositivos, como um dispositivo móvel e um navegador de Internet.

Acerca da indicação de tempo

Quando regista um evento do utilizador, certifique-se de que inclui uma indicação de tempo precisa de quando o evento ocorreu. As datas/horas precisas garantem que os seus eventos são armazenados pela ordem correta. As datas/horas são registadas automaticamente para eventos recolhidos através do píxel do JavaScript. Quando importa eventos, tem de indicar a data/hora no campo eventTime no formato especificado pela RFC 3339.