REST Resource: projects.locations.dataStores.userEvents

Recurso: UserEvent

O UserEvent capta todas as informações de metadados que a API Discovery Engine precisa de saber sobre a forma como os utilizadores finais interagem com o seu Website.

Representação JSON 
{
  "eventType": string,
  "conversionType": string,
  "userPseudoId": string,
  "engine": string,
  "dataStore": string,
  "eventTime": string,
  "userInfo": {
    object (UserInfo)
  },
  "directUserRequest": boolean,
  "sessionId": string,
  "pageInfo": {
    object (PageInfo)
  },
  "attributionToken": string,
  "filter": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panel": {
    object (PanelInfo)
  },
  "searchInfo": {
    object (SearchInfo)
  },
  "completionInfo": {
    object (CompletionInfo)
  },
  "transactionInfo": {
    object (TransactionInfo)
  },
  "tagIds": [
    string
  ],
  "promotionIds": [
    string
  ],
  "attributes": {
    string: {
      "text": [
        string
      ],
      "numbers": [
        number
      ]
    },
    ...
  },
  "mediaInfo": {
    object (MediaInfo)
  },
  "panels": [
    {
      object (PanelInfo)
    }
  ]
}
Campos
eventType

string

Obrigatório. Tipo de evento de utilizador. Os valores permitidos são:

Valores genéricos:

  • search: pesquise documentos.
  • view-item: vista detalhada de uma página de um documento.
  • view-item-list: vista de um painel ou de uma lista ordenada de documentos.
  • view-home-page: vista da página inicial.
  • view-category-page: visualização de uma página de categoria, por exemplo, Página inicial > Homem > Jeans

Valores relacionados com o retalho:

  • add-to-cart: adicionar um ou mais artigos ao carrinho, por exemplo, em compras online de retalho
  • purchase: compre um ou mais artigos

Valores relacionados com multimédia:

  • media-play: iniciar/retomar a visualização de um vídeo, a reprodução de uma música, etc.
  • media-complete: terminou ou parou a meio de um vídeo, uma música, etc.

Valor de conversão personalizado:

  • conversion: evento de conversão definido pelo cliente.
conversionType

string

Opcional. Tipo de conversão.

Obrigatório se UserEvent.event_type for conversion. Este é um nome de conversão definido pelo cliente em letras minúsculas ou números separados por "-", como "ver", "boa-visita", etc.

Não defina o campo se UserEvent.event_type não for conversion. Isto mistura o evento de conversão personalizado com eventos predefinidos, como search, view-item, etc.
userPseudoId

string

Obrigatório. Um identificador exclusivo para acompanhar os visitantes.

Por exemplo, isto pode ser implementado com um cookie HTTP, que deve ser capaz de identificar de forma exclusiva um visitante num único dispositivo. Este identificador exclusivo não deve ser alterado se o visitante iniciar/terminar sessão no Website.

Não defina o campo para o mesmo ID fixo para diferentes utilizadores. Isto mistura o histórico de eventos desses utilizadores, o que resulta numa qualidade do modelo degradada.

O campo tem de ser uma string codificada em UTF-8 com um limite de 128 carateres. Caso contrário, é devolvido um erro INVALID_ARGUMENT.

O campo não deve conter PII nem dados do utilizador. Recomendamos que use o ID do cliente do Google Analytics para este campo.
engine

string

O Engine nome do recurso, no formato projects/{project}/locations/{location}/collections/{collectionId}/engines/{engineId}.

Opcional. Apenas necessário para eventos do utilizador produzidos pelo Engine. Por exemplo, eventos de utilizadores da pesquisa combinada.
dataStore

string

O nome completo do recurso DataStore, no formato projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}.

Opcional. Apenas obrigatório para eventos de utilizadores cuja loja de dados não possa ser determinada por UserEvent.engine ou UserEvent.documents. Se o armazenamento de dados estiver definido no elemento principal dos pedidos de eventos de utilizador de gravação/importação/recolha, este campo pode ser omitido.
eventTime

string (Timestamp format)

Obrigatório apenas para o método UserEventService.ImportUserEvents. Data/hora em que ocorreu o evento do utilizador.

Usa RFC 3339, em que o resultado gerado é sempre normalizado em Z e usa 0, 3, 6 ou 9 dígitos fracionários. Também são aceites desvios diferentes de "Z". Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
userInfo

object (UserInfo)

Informações sobre o utilizador final.
directUserRequest

boolean

Deve ser definido como verdadeiro se o pedido for feito diretamente pelo utilizador final, caso em que o UserEvent.user_info.user_agent pode ser preenchido a partir do pedido HTTP.

Esta flag só deve ser definida se o pedido da API for feito diretamente pelo utilizador final, como uma app para dispositivos móveis (e não se um gateway ou um servidor estiver a processar e a enviar os eventos do utilizador).

Isto não deve ser definido quando usar a etiqueta JavaScript no UserEventService.CollectUserEvent.
sessionId

string

Um identificador exclusivo para acompanhar uma sessão de visitante com um limite de comprimento de 128 bytes. Uma sessão é uma agregação do comportamento de um utilizador final num período.

Uma diretriz geral para preencher o sessionId:

  1. Se o utilizador não tiver atividade durante 30 minutos, deve ser atribuído um novo sessionId.
  2. O sessionId deve ser exclusivo para todos os utilizadores. Sugerimos que use uuid ou adicione UserEvent.user_pseudo_id como prefixo.
pageInfo

object (PageInfo)

Metadados da página, como categorias e outras informações críticas para determinados tipos de eventos, como view-category-page.
attributionToken

string

Token para atribuir uma resposta da API a ações do utilizador para acionar o evento.

Altamente recomendado para eventos de utilizadores que são o resultado de RecommendationService.Recommend. Este campo permite a atribuição precisa do desempenho do modelo de recomendação.

O valor tem de ser um dos seguintes:

Este token permite-nos atribuir com precisão a visualização de página ou a conclusão da conversão ao evento e à resposta de previsão específica que contém este produto clicado/comprado. Se o utilizador clicar no produto K nos resultados da recomendação, transmita RecommendResponse.attribution_token como um parâmetro de URL para a página do produto K. Quando registar eventos na página do produto K, registe o RecommendResponse.attribution_token neste campo.
filter

string

A sintaxe do filtro consiste numa linguagem de expressão para criar um predicado a partir de um ou mais campos dos documentos que estão a ser filtrados.

Um exemplo é para eventos search, em que o SearchRequest associado pode conter uma expressão de filtro em SearchRequest.filter em conformidade com https://google.aip.dev/160#filtering.

Da mesma forma, para eventos view-item-list gerados a partir de um RecommendRequest, este campo pode ser preenchido diretamente a partir de RecommendRequest.filter em conformidade com https://google.aip.dev/160#filtering.

O valor tem de ser uma string codificada em UTF-8 com um limite de 1000 carateres. Caso contrário, é devolvido um erro INVALID_ARGUMENT.
documents[]

object (DocumentInfo)

Lista de Documents associados a este evento do utilizador.

Este campo é opcional, exceto para os seguintes tipos de eventos:

  • view-item
  • add-to-cart
  • purchase
  • media-play
  • media-complete

Num evento search, este campo representa os documentos devolvidos ao utilizador final na página atual (o utilizador final pode ainda não ter terminado de navegar em toda a página). Quando uma nova página é devolvida ao utilizador final, após a paginação/filtragem/ordenação, mesmo para a mesma consulta, é desejável um novo evento search com UserEvent.documents diferentes.
panel

object (PanelInfo)

Metadados do painel associados a este evento do utilizador.
searchInfo

object (SearchInfo)

SearchService.Search detalhes relacionados com o evento.

Este campo deve ser definido para o evento search.
completionInfo

object (CompletionInfo)

CompletionService.CompleteQuery detalhes relacionados com o evento.

Este campo deve ser definido para o evento search quando a função de preenchimento automático está ativada e o utilizador clica numa sugestão de pesquisa.
transactionInfo

object (TransactionInfo)

Os metadados da transação (se existirem) associados a este evento do utilizador.
tagIds[]

string

Uma lista de identificadores dos grupos experimentais independentes a que este evento do utilizador pertence. Isto é usado para distinguir entre eventos de utilizadores associados a diferentes configurações de experiências.
promotionIds[]

string

Os IDs das promoções, se este for um evento associado a promoções. Atualmente, este campo está restrito a, no máximo, um ID.
attributes

map (key: string, value: object)

Funcionalidades de eventos do utilizador adicionais a incluir no modelo de recomendações. Estes atributos NÃO podem conter dados que precisem de ser analisados ou processados posteriormente, por exemplo, JSON ou outras codificações.

Se fornecer atributos personalizados para eventos de utilizadores carregados, inclua-os também nos eventos de utilizadores que associa a pedidos de previsão. A formatação dos atributos personalizados tem de ser consistente entre os eventos importados e os eventos fornecidos com pedidos de previsão. Isto permite que a API Discovery Engine use esses atributos personalizados ao preparar modelos e publicar previsões, o que ajuda a melhorar a qualidade das recomendações.

Este campo tem de cumprir todos os critérios abaixo. Caso contrário, é devolvido um erro INVALID_ARGUMENT:

  • A chave tem de ser uma string codificada em UTF-8 com um limite de comprimento de 5000 carateres.
  • Para atributos de texto, são permitidos, no máximo, 400 valores. Não são permitidos valores vazios. Cada valor tem de ser uma string com codificação UTF-8 com um limite de comprimento de 256 carateres.
  • Para atributos numéricos, são permitidos, no máximo, 400 valores.

Para recomendações de produtos, um exemplo de informações adicionais do utilizador é traffic_channel, que indica como um utilizador chega ao site. Os utilizadores podem chegar ao site acedendo diretamente ao mesmo, através da Pesquisa Google ou de outras formas.
attributes.text[]

string

Os valores textuais deste atributo personalizado. Por exemplo, ["yellow", "green"] quando a chave é "cor".

Não é permitida uma string vazia. Caso contrário, é devolvido um erro INVALID_ARGUMENT.

Tem de definir exatamente uma das propriedades CustomAttribute.text ou CustomAttribute.numbers. Caso contrário, é devolvido um erro INVALID_ARGUMENT.
attributes.numbers[]

number

Os valores numéricos deste atributo personalizado. Por exemplo, [2.3, 15.4] quando a chave é "lengths_cm".

Tem de definir exatamente uma das propriedades CustomAttribute.text ou CustomAttribute.numbers. Caso contrário, é devolvido um erro INVALID_ARGUMENT.
mediaInfo

object (MediaInfo)

Informações específicas de multimédia.
panels[]

object (PanelInfo)

Opcional. Lista de painéis associados a este evento. Usado para dados de impressões ao nível da página.

UserInfo

Informações de um utilizador final.

Representação JSON 
{
  "userId": string,
  "userAgent": string,
  "timeZone": string
}
Campos
userId

string

Altamente recomendado para utilizadores com sessão iniciada. Identificador exclusivo do utilizador com sessão iniciada, como um nome de utilizador. Não defina para utilizadores anónimos.

Use sempre um valor com hash para este ID.

Não defina o campo para o mesmo ID fixo para diferentes utilizadores. Isto mistura o histórico de eventos desses utilizadores, o que resulta numa qualidade do modelo degradada.

O campo tem de ser uma string codificada em UTF-8 com um limite de 128 carateres. Caso contrário, é devolvido um erro INVALID_ARGUMENT.
userAgent

string

Agente do utilizador, conforme incluído no cabeçalho HTTP.

O campo tem de ser uma string codificada em UTF-8 com um limite de 1000 carateres. Caso contrário, é devolvido um erro INVALID_ARGUMENT.

Isto não deve ser definido quando usar os relatórios de eventos do lado do cliente com o GTM ou a etiqueta JavaScript no UserEventService.CollectUserEvent ou se UserEvent.direct_user_request estiver definido.
timeZone

string

Opcional. Fuso horário da IANA, por exemplo, Europe/Budapest.

PageInfo

Informações detalhadas da página.

Representação JSON 
{
  "pageviewId": string,
  "pageCategory": string,
  "uri": string,
  "referrerUri": string
}
Campos
pageviewId

string

Um ID exclusivo de uma visualização de página Web.

Este valor deve ser mantido igual para todos os eventos de utilizador acionados a partir da mesma visualização de página. Por exemplo, uma visualização da página de detalhes de um artigo pode acionar vários eventos à medida que o utilizador navega na página. A propriedade pageviewId deve ser mantida igual para todos estes eventos, para que possam ser agrupados corretamente.

Quando usa os relatórios de eventos do lado do cliente com o píxel de JavaScript e o Gestor de Etiquetas da Google, este valor é preenchido automaticamente.
pageCategory

string

A categoria mais específica associada a uma página de categoria.

Para representar o caminho completo da categoria, use o sinal ">" para separar as diferentes hierarquias. Se ">" fizer parte do nome da categoria, substitua-o por outros carateres.

As páginas de categorias incluem páginas especiais, como saldos ou promoções. Por exemplo, uma página de promoção especial pode ter a seguinte hierarquia de categorias: "pageCategory" : "Sales > 2017 Black Friday Deals".

Obrigatório para eventos view-category-page. Outros tipos de eventos não devem definir este campo. Caso contrário, é devolvido um erro INVALID_ARGUMENT.
uri

string

URL completo (window.location.href) da página atual do utilizador.

Quando usa os relatórios de eventos do lado do cliente com o píxel de JavaScript e o Gestor de Etiquetas da Google, este valor é preenchido automaticamente. Comprimento máximo: 5000 carateres.
referrerUri

string

O URL de referência da página atual.

Quando usa os relatórios de eventos do lado do cliente com o píxel de JavaScript e o Gestor de Etiquetas da Google, este valor é preenchido automaticamente. No entanto, algumas restrições de privacidade do navegador podem fazer com que este campo fique vazio.

DocumentInfo

Informações detalhadas do documento associadas a um evento do utilizador.

Representação JSON 
{
  "promotionIds": [
    string
  ],
  "joined": boolean,

  // Union field document_descriptor can be only one of the following:
  "id": string,
  "name": string,
  "uri": string
  // End of list of possible types for union field document_descriptor.
  "quantity": integer,
  "conversionValue": number
}
Campos
promotionIds[]

string

Os IDs das promoções associadas a este documento. Atualmente, este campo está restrito a, no máximo, um ID.
joined

boolean

Apenas saída. Se é possível encontrar o documento referenciado no repositório de dados.

Campo de união document_descriptor. Um descritor obrigatório do Document associado.

  • Se id for especificado, os valores predefinidos de {location}, {collection_id}, {data_store_id} e {branch_id} são usados ao anotar com o documento armazenado.

  • Se name for especificado, os valores fornecidos (valores predefinidos permitidos) para {location}, {collection_id}, {data_store_id} e {branch_id} são usados ao anotar com o documento armazenado. document_descriptor só pode ser uma das seguintes opções:
id

string

O ID do recurso Document.
name

string

O nome completo do recurso Document, no formato: projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}/branches/{branchId}/documents/{documentId}
uri

string

O URI Document só é permitido para armazenamentos de dados de Websites.
quantity

integer

Quantidade do documento associado ao evento do utilizador. A predefinição é 1.

Por exemplo, este campo é 2 se estiverem envolvidas duas quantidades do mesmo documento num evento add-to-cart.

Obrigatório para eventos dos seguintes tipos de eventos:

  • add-to-cart
  • purchase
conversionValue

number

Opcional. O valor de conversão associado a este documento. Tem de ser definido se UserEvent.event_type for "conversion".

Por exemplo, um valor de 1000 significa que foram gastos 1000 segundos a ver um documento para o tipo de conversão watch.

PanelInfo

Informações detalhadas do painel associadas a um evento do utilizador.

Representação JSON 
{
  "panelId": string,
  "displayName": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panelPosition": integer,
  "totalPanels": integer
}
Campos
panelId

string

Obrigatório. O ID do painel.
displayName

string

O nome a apresentar do painel.
documents[]

object (DocumentInfo)

Opcional. Os IDs dos documentos associados a este painel.
panelPosition

integer

A posição ordenada do painel, se for apresentado ao utilizador com outros painéis. Se estiver definido, totalPanels também tem de estar definido.
totalPanels

integer

O número total de painéis, incluindo este, apresentados ao utilizador. Tem de ser definido se panelPosition estiver definido.

SearchInfo

Informações de pesquisa detalhadas.

Representação JSON 
{
  "searchQuery": string,
  "orderBy": string,
  "offset": integer
}
Campos
searchQuery

string

A consulta de pesquisa do utilizador.

Consulte SearchRequest.query para ver a definição.

O valor tem de ser uma string codificada em UTF-8 com um limite de 5000 carateres. Caso contrário, é devolvido um erro INVALID_ARGUMENT.

É necessário, pelo menos, um de searchQuery ou PageInfo.page_category para eventos search. Outros tipos de eventos não devem definir este campo. Caso contrário, é devolvido um erro INVALID_ARGUMENT.
orderBy

string

A ordem em que os produtos são devolvidos, se aplicável.

Consulte SearchRequest.order_by para ver a definição e a sintaxe.

O valor tem de ser uma string codificada em UTF-8 com um limite de 1000 carateres. Caso contrário, é devolvido um erro INVALID_ARGUMENT.

Esta opção só pode ser definida para eventos search. Outros tipos de eventos não devem definir este campo. Caso contrário, é devolvido um erro INVALID_ARGUMENT.
offset

integer

Um número inteiro que especifica o desvio atual para a paginação (a localização inicial com índice 0, entre os produtos considerados relevantes pela API).

Consulte SearchRequest.offset para ver a definição.

Se este campo for negativo, é devolvido um INVALID_ARGUMENT.

Esta opção só pode ser definida para eventos search. Outros tipos de eventos não devem definir este campo. Caso contrário, é devolvido um erro INVALID_ARGUMENT.

CompletionInfo

Informações de conclusão detalhadas, incluindo o token de atribuição de conclusão e as informações de conclusão clicadas.

Representação JSON 
{
  "selectedSuggestion": string,
  "selectedPosition": integer
}
Campos
selectedSuggestion

string

Utilizador final selecionado CompleteQueryResponse.QuerySuggestion.suggestion.
selectedPosition

integer

Posição CompleteQueryResponse.QuerySuggestion.suggestion selecionada pelo utilizador final, a partir de 0.

TransactionInfo

Uma transação representa toda a transação de compra.

Representação JSON 
{
  "currency": string,
  "transactionId": string,
  "value": number,
  "tax": number,
  "cost": number,
  "discountValue": number
}
Campos
currency

string

Obrigatório. Código da moeda. Use o código ISO-4217 de três carateres.
transactionId

string

O ID da transação com um limite de comprimento de 128 carateres.
value

number

Obrigatório. Valor total não nulo associado à transação. Este valor pode incluir o envio, impostos ou outros ajustes ao valor total que quer incluir.
tax

number

Todos os impostos associados à transação.
cost

number

Todos os custos associados aos produtos. Estes podem ser custos de fabrico, despesas de envio não suportadas pelo utilizador final ou quaisquer outros custos, de modo que:
discountValue

number

O valor total dos descontos aplicados a esta transação. Esta figura deve ser excluída de TransactionInfo.value

Por exemplo, se um utilizador pagou o montante TransactionInfo.value, o valor nominal (antes do desconto) da transação é a soma de TransactionInfo.value e TransactionInfo.discount_value

Isto significa que o lucro é calculado da mesma forma, independentemente do valor do desconto, e que TransactionInfo.discount_value pode ser superior a TransactionInfo.value:

MediaInfo

Informações de eventos do utilizador específicas de multimédia.

Representação JSON 
{
  "mediaProgressDuration": string,
  "mediaProgressPercentage": number
}
Campos
mediaProgressDuration

string (Duration format)

O tempo de progresso do conteúdo multimédia em segundos, se aplicável. Por exemplo, se o utilizador final tiver terminado 90 segundos de um vídeo de reprodução, MediaInfo.media_progress_duration.seconds deve ser definido como 90.

Uma duração em segundos com até nove dígitos fracionários, que termina com "s". Exemplo: "3.5s".
mediaProgressPercentage

number

O progresso dos conteúdos multimédia deve ser calculado apenas com base no mediaProgressDuration em relação à duração total dos conteúdos multimédia.

Este valor tem de estar entre [0, 1.0] inclusive.

Se não se tratar de uma reprodução ou não for possível calcular o progresso (por exemplo, uma stream em direto em curso), este campo deve ser anulado.

Métodos

collect

 Escreve um único evento de utilizador a partir do navegador.

import

 Importação em massa de eventos de utilizadores.

purge

 Elimina permanentemente todos os eventos do utilizador especificados pelo filtro fornecido.

write

 Escreve um único evento de utilizador.