REST Resource: projects.locations.dataStores.userEvents

Recurso: UserEvent

O UserEvent captura todas as informações de metadados que a API Discovery Engine precisa saber sobre como os usuários finais interagem com seu site.

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 do usuário. Os valores permitidos são:

Valores genéricos:

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

Valores relacionados ao varejo:

  • add-to-cart: adicionar um ou mais itens ao carrinho, por exemplo, em compras on-line no varejo
  • purchase: comprar um ou mais itens

Valores relacionados à mídia:

  • media-play: comece/retome a exibição de um vídeo, a reprodução de uma música etc.
  • media-complete: terminou ou parou no meio de um vídeo, 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. É um nome de conversão definido pelo cliente em letras minúsculas ou números separados por "-", como "assistir", "boa-visita" etc.

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

string

Obrigatório. Um identificador exclusivo para rastrear visitantes.

Por exemplo, isso pode ser implementado com um cookie HTTP, que deve ser capaz de identificar um visitante de maneira exclusiva em um único dispositivo. Esse identificador exclusivo não deve mudar se o visitante fizer login/logout do site.

Não defina o campo com o mesmo ID fixo para usuários diferentes. Isso mistura o histórico de eventos desses usuários, o que resulta em uma qualidade de modelo degradada.

O campo precisa ser uma string codificada em UTF-8 com um limite de 128 caracteres. Caso contrário, um erro INVALID_ARGUMENT será retornado.

O campo não pode conter PII ou dados do usuário. Recomendamos usar o Client-ID do Google Analytics para esse campo.
engine

string

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

Opcional. Só é obrigatório para eventos de usuário produzidos por Engine. Por exemplo, eventos de usuário da pesquisa combinada.
dataStore

string

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

Opcional. Necessário apenas para eventos de usuário cujo repositório de dados não pode ser determinado por UserEvent.engine ou UserEvent.documents. Se o repositório de dados estiver definido no pai das solicitações de evento do usuário de gravação/importação/coleta, esse campo poderá ser omitido.
eventTime

string (Timestamp format)

Obrigatório apenas para o método UserEventService.ImportUserEvents. Carimbo de data/hora de quando o evento do usuário aconteceu.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. 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 usuário final.
directUserRequest

boolean

Defina como "true" se a solicitação for feita diretamente pelo usuário final. Nesse caso, o UserEvent.user_info.user_agent pode ser preenchido com base na solicitação HTTP.

Essa flag só deve ser definida se a solicitação de API for feita diretamente pelo usuário final, como um app para dispositivos móveis, e não se um gateway ou servidor estiver processando e enviando os eventos do usuário.

Não defina esse parâmetro ao usar a tag JavaScript em UserEventService.CollectUserEvent.
sessionId

string

Um identificador exclusivo para rastrear uma sessão de visitante com um limite de 128 bytes. Uma sessão é uma agregação do comportamento de um usuário final em um período.

Uma diretriz geral para preencher o sessionId:

  1. Se o usuário não tiver atividade por 30 minutos, um novo sessionId deverá ser atribuído.
  2. O sessionId precisa ser exclusivo entre os usuários. Sugerimos usar uuid ou adicionar UserEvent.user_pseudo_id como prefixo.
pageInfo

object (PageInfo)

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

string

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

Altamente recomendado para eventos do usuário que são resultado de RecommendationService.Recommend. Esse campo permite a atribuição precisa da performance do modelo de recomendação.

O valor precisa ser um dos seguintes:

Com ele, podemos 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 o produto clicado/comprado. Se o usuário 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. Ao registrar eventos na página do produto K, faça o registro do RecommendResponse.attribution_token nesse campo.
filter

string

A sintaxe do filtro consiste em uma linguagem de expressão para construir um predicado a partir de um ou mais campos dos documentos que estão sendo filtrados.

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

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

O valor precisa ser uma string codificada em UTF-8 com um limite de 1.000 caracteres. Caso contrário, um erro INVALID_ARGUMENT será retornado.
documents[]

object (DocumentInfo)

Lista de Documents associados a esse evento do usuário.

Esse campo é opcional, exceto para os seguintes tipos de evento:

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

Em um evento search, esse campo representa os documentos retornados ao usuário final na página atual. O usuário final pode não ter terminado de navegar por toda a página. Quando uma nova página é retornada ao usuário final, após paginação/filtragem/ordenação, mesmo para a mesma consulta, um novo evento search com UserEvent.documents diferente é desejado.
panel

object (PanelInfo)

Metadados do painel associados a esse evento do usuário.
searchInfo

object (SearchInfo)

Detalhes de SearchService.Search relacionados ao evento.

Esse campo precisa ser definido para o evento search.
completionInfo

object (CompletionInfo)

Detalhes de CompletionService.CompleteQuery relacionados ao evento.

Esse campo precisa ser definido para o evento search quando a função de preenchimento automático está ativada e o usuário clica em uma sugestão de pesquisa.
transactionInfo

object (TransactionInfo)

Os metadados da transação (se houver) associados a esse evento do usuário.
tagIds[]

string

Uma lista de identificadores dos grupos de experimentos independentes a que este evento do usuário pertence. Usado para distinguir eventos de usuário associados a diferentes configurações de experimentos.
promotionIds[]

string

Os IDs das promoções, se este for um evento associado a elas. No momento, esse campo é restrito a no máximo um ID.
attributes

map (key: string, value: object)

Recursos extras de eventos do usuário para incluir no modelo de recomendação. Esses atributos NÃO podem conter dados que precisam ser analisados ou processados posteriormente, como JSON ou outras codificações.

Se você fornecer atributos personalizados para eventos do usuário ingeridos, inclua-os também nos eventos do usuário associados às solicitações de previsão. A formatação de atributos personalizados precisa ser consistente entre os eventos importados e os eventos fornecidos com solicitações de previsão. Isso permite que a API Discovery Engine use esses atributos personalizados ao treinar modelos e veicular previsões, o que ajuda a melhorar a qualidade das recomendações.

Esse campo precisa atender a todos os critérios abaixo. Caso contrário, um erro INVALID_ARGUMENT será retornado:

  • A chave precisa ser uma string codificada em UTF-8 com um limite de 5.000 caracteres.
  • Para atributos de texto, o limite é de 400 valores. Valores vazios não são permitidos. Cada valor precisa ser uma string codificada em UTF-8 com um limite de 256 caracteres.
  • Para atributos numéricos, o limite é de 400 valores.

Para recomendações de produtos, um exemplo de informação extra do usuário é traffic_channel, que é como um usuário chega ao site. Os usuários podem chegar ao site diretamente, pela Pesquisa Google ou de outras maneiras.
attributes.text[]

string

Os valores de texto desse atributo personalizado. Por exemplo, ["yellow", "green"] quando a chave é "color".

Não é permitido usar uma string vazia. Caso contrário, um erro INVALID_ARGUMENT será retornado.

É necessário definir exatamente um CustomAttribute.text ou CustomAttribute.numbers. Caso contrário, é retornado um erro INVALID_ARGUMENT.
attributes.numbers[]

number

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

É necessário definir exatamente um CustomAttribute.text ou CustomAttribute.numbers. Caso contrário, é retornado um erro INVALID_ARGUMENT.
mediaInfo

object (MediaInfo)

Informações específicas da mídia.
panels[]

object (PanelInfo)

Opcional. Lista de painéis associados a este evento. Usado para dados de impressão no nível da página.

UserInfo

Informações de um usuário final.

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

string

Altamente recomendado para usuários conectados. Identificador exclusivo do usuário conectado, como um nome de usuário. Não defina para usuários anônimos.

Sempre use um valor de hash para esse ID.

Não defina o campo com o mesmo ID fixo para usuários diferentes. Isso mistura o histórico de eventos desses usuários, o que resulta em uma qualidade de modelo degradada.

O campo precisa ser uma string codificada em UTF-8 com um limite de 128 caracteres. Caso contrário, um erro INVALID_ARGUMENT será retornado.
userAgent

string

User agent incluído no cabeçalho HTTP.

O campo precisa ser uma string codificada em UTF-8 com um limite de 1.000 caracteres. Caso contrário, um erro INVALID_ARGUMENT será retornado.

Não defina isso ao usar o relatório de eventos do lado do cliente com a tag do GTM ou do JavaScript em 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 da Web.

Isso precisa ser mantido igual para todos os eventos de usuário acionados na mesma visualização de página. Por exemplo, uma visualização de página de detalhes do item pode acionar vários eventos enquanto o usuário navega pela página. A propriedade pageviewId precisa ser mantida a mesma para todos esses eventos, de modo que eles possam ser agrupados corretamente.

Ao usar a geração de relatórios de eventos do lado do cliente com o pixel JavaScript e o Gerenciador de tags do Google, esse 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 diferentes hierarquias. Se ">" fizer parte do nome da categoria, substitua por outros caracteres.

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

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

string

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

Ao usar a geração de relatórios de eventos do lado do cliente com o pixel JavaScript e o Gerenciador de tags do Google, esse valor é preenchido automaticamente. O tamanho máximo é de 5.000 caracteres.
referrerUri

string

O URL de indicação da página atual.

Ao usar a geração de relatórios de eventos do lado do cliente com o pixel JavaScript e o Gerenciador de tags do Google, esse valor é preenchido automaticamente. No entanto, algumas restrições de privacidade do navegador podem fazer com que esse campo fique vazio.

DocumentInfo

Informações detalhadas do documento associadas a um evento do usuário.

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 de promoção associados a este documento. No momento, esse campo é restrito a no máximo um ID.
joined

boolean

Apenas saída. Se o documento referenciado pode ser encontrado no repositório de dados.

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

  • Se id for especificado, os valores padrão de {location}, {collection_id}, {data_store_id} e {branch_id} serão usados ao fazer anotações com o documento armazenado.

  • Se name for especificado, os valores fornecidos (valores padrão permitidos) para {location}, {collection_id}, {data_store_id} e {branch_id} serão usados ao fazer anotações com o documento armazenado. document_descriptor pode ser apenas de um dos tipos a seguir:
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, que só é permitido para repositórios de dados de sites.
quantity

integer

Quantidade do documento associado ao evento do usuário. O padrão é 1.

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

Obrigatório para eventos dos seguintes tipos:

  • add-to-cart
  • purchase
conversionValue

number

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

Por exemplo, um valor de 1.000 significa que 1.000 segundos foram gastos visualizando um documento para o tipo de conversão watch.

PanelInfo

Informações detalhadas do painel associadas a um evento do usuário.

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 de exibição do painel.
documents[]

object (DocumentInfo)

Opcional. Os IDs de documento associados a este painel.
panelPosition

integer

A posição ordenada do painel, se ele for mostrado ao usuário com outros painéis. Se definido, totalPanels também precisa ser definido.
totalPanels

integer

O número total de painéis, incluindo este, mostrados ao usuário. Precisa ser definido se panelPosition estiver definido.

SearchInfo

Informações detalhadas da pesquisa.

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

string

A consulta de pesquisa do usuário.

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

O valor precisa ser uma string codificada em UTF-8 com um limite de 5.000 caracteres. Caso contrário, um erro INVALID_ARGUMENT será retornado.

É necessário incluir pelo menos uma das seguintes propriedades: searchQuery ou PageInfo.page_category para eventos search. Outros tipos de eventos não devem definir esse campo. Caso contrário, um erro INVALID_ARGUMENT será retornado.
orderBy

string

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

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

O valor precisa ser uma string codificada em UTF-8 com um limite de 1.000 caracteres. Caso contrário, um erro INVALID_ARGUMENT será retornado.

Isso só pode ser definido para eventos search. Outros tipos de eventos não devem definir esse campo. Caso contrário, um erro INVALID_ARGUMENT será retornado.
offset

integer

Um número inteiro que especifica o deslocamento atual para paginação (o local inicial indexado em 0, entre os produtos considerados relevantes pela API).

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

Se esse campo for negativo, um INVALID_ARGUMENT será retornado.

Isso só pode ser definido para eventos search. Outros tipos de eventos não devem definir esse campo. Caso contrário, um erro INVALID_ARGUMENT será retornado.

CompletionInfo

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

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

string

O usuário final selecionou CompleteQueryResponse.QuerySuggestion.suggestion.
selectedPosition

integer

Posição CompleteQueryResponse.QuerySuggestion.suggestion selecionada pelo usuário final, começando em 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 caracteres.
transactionId

string

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

number

Obrigatório. Valor total diferente de zero associado à transação. Esse valor pode incluir frete, tributos ou outros ajustes no valor total que você quer incluir.
tax

number

Todos os tributos associados à transação.
cost

number

Todos os custos associados aos produtos. Podem ser custos de fabricação, despesas de frete não pagas pelo usuário final ou outros custos, de modo que:
discountValue

number

O valor total dos descontos aplicados a esta transação. Esse valor precisa ser excluído de TransactionInfo.value

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

Isso significa que o lucro é calculado da mesma forma, independente do valor do desconto, e que TransactionInfo.discount_value pode ser maior que TransactionInfo.value:

MediaInfo

Informações de eventos do usuário específicas da mídia.

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

string (Duration format)

O tempo de progresso da mídia em segundos, se aplicável. Por exemplo, se o usuário final tiver terminado 90 segundos de um vídeo de reprodução, MediaInfo.media_progress_duration.seconds deverá ser definido como 90.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".
mediaProgressPercentage

number

O progresso da mídia deve ser calculado usando apenas o mediaProgressDuration em relação à duração total da mídia.

Esse valor precisa estar entre [0, 1.0], inclusive.

Se não for uma reprodução ou se o progresso não puder ser calculado (por exemplo, uma transmissão ao vivo em andamento), esse campo não deve ser definido.

Métodos

collect

 Grava um único evento do usuário no navegador.

import

 Importação em massa de eventos de usuário.

purge

 Exclui permanentemente todos os eventos de usuário especificados pelo filtro fornecido.

write

 Grava um único evento do usuário.