- Recurso: UserEvent
- UserInfo
- PreciseLocation
- PageInfo
- DocumentInfo
- PanelInfo
- SearchInfo
- CompletionInfo
- TransactionInfo
- MediaInfo
- Feedback
- FeedbackType
- Motivo
- ConversationInfo
- FeedbackSource
- Métodos
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 ( |
| Campos | |
|---|---|
eventType |
Obrigatório. Tipo de evento do usuário. Os valores permitidos são: Valores genéricos:
Valores relacionados ao varejo:
Valores relacionados à mídia:
Valor de conversão personalizado:
|
conversionType |
Opcional. Tipo de conversão. Obrigatório se Não defina o campo se |
userPseudoId |
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. Este identificador único não deve mudar se o visitante entrar ou sair 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 O campo não pode conter PII nem dados do usuário. Recomendamos o uso do ID do cliente do Google Analytics para este campo. |
engine |
O nome do recurso Opcional. Só é obrigatório para eventos de usuário produzidos por |
dataStore |
O nome completo do recurso Opcional. Necessário apenas para eventos de usuário cujo repositório de dados não pode ser determinado por |
eventTime |
Obrigatório apenas para o método 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: |
userInfo |
Informações sobre o usuário final. |
directUserRequest |
Defina como "true" se a solicitação for feita diretamente pelo usuário final. Nesse caso, o 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 |
sessionId |
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:
|
pageInfo |
Metadados da página, como categorias e outras informações importantes para determinados tipos de eventos, como |
attributionToken |
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 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 |
filter |
Opcional. 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. Um exemplo é para eventos Da mesma forma, para eventos O valor precisa ser uma string codificada em UTF-8 com um limite de 1.000 caracteres. Caso contrário, um erro |
documents[] |
Lista de Esse campo é opcional, exceto para os seguintes tipos de evento:
Em um evento |
panel |
Metadados do painel associados a esse evento do usuário. |
searchInfo |
Detalhes de Esse campo precisa ser definido para o evento |
completionInfo |
Detalhes de Esse campo precisa ser definido para o evento |
transactionInfo |
Os metadados da transação (se houver) associados a esse evento do usuário. |
tagIds[] |
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[] |
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 |
Recursos extras de eventos do usuário a serem incluídos 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 do Discovery Engine utilize esses atributos personalizados ao treinar modelos e fornecer 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
Para recomendações de produtos, um exemplo de informação extra do usuário é |
attributes.text[] |
Os valores de texto desse atributo personalizado. Por exemplo, Não é permitido usar uma string vazia. Caso contrário, um erro É necessário definir exatamente um |
attributes.numbers[] |
Os valores numéricos desse atributo personalizado. Por exemplo, É necessário definir exatamente um |
mediaInfo |
Informações específicas da mídia. |
panels[] |
Opcional. Lista de painéis associados a esse evento. Usado para dados de impressão no nível da página. |
feedback |
Opcional. Esse campo é opcional, exceto para os tipos de evento |
entity |
Opcional. Representa a entidade para clientes que podem executar várias entidades, domínios, sites ou regiões diferentes, por exemplo, |
UserInfo
Informações de um usuário final.
| Representação JSON |
|---|
{
"userId": string,
"userAgent": string,
"timeZone": string,
"preciseLocation": {
object ( |
| Campos | |
|---|---|
userId |
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 Representa um ID opaco para a API Search. A API Search não interpreta o valor de forma alguma. Esse campo é usado para associar eventos a um usuário em várias sessões se os eventos estiverem sendo enviados. |
userAgent |
Agente do usuário conforme 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 Não defina isso ao usar o relatório de eventos do lado do cliente com a tag do GTM ou do JavaScript em |
timeZone |
Opcional. Fuso horário IANA, por exemplo, Europa/Budapeste. |
preciseLocation |
Opcional. Somente entrada. Local exato do usuário. É usado na classificação personalizada para calcular a distância entre o usuário e os documentos relevantes. |
PreciseLocation
Informações de localização exata com várias opções de representação.
| Representação JSON |
|---|
{
// The following is a list of mutually exclusive fields. At most one of the
// fields will be set in a response:
"point": {
object ( |
| Campos | |
|---|---|
| Confira a seguir uma lista de campos mutuamente exclusivos. No máximo, um dos campos será definido em uma resposta: | |
point |
Opcional. Local representado por um ponto de latitude/longitude. |
address |
local representado por um endereço em linguagem natural. Será geocodificado e convertido em um ponto ou um polígono. |
| Fim dos campos mutuamente exclusivos. | |
PageInfo
Informações detalhadas da página.
| Representação JSON |
|---|
{ "pageviewId": string, "pageCategory": string, "uri": string, "referrerUri": string } |
| Campos | |
|---|---|
pageviewId |
Um ID exclusivo de uma visualização de página da Web. Ele precisa ser o mesmo 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 Ao usar a geração de relatórios de eventos do lado do cliente com o pixel JavaScript e o Google Tag Manager, esse valor é preenchido automaticamente. |
pageCategory |
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 outro(s) caractere(s). 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: Obrigatório para eventos |
uri |
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 Google Tag Manager, esse valor é preenchido automaticamente. O tamanho máximo é de 5.000 caracteres. |
referrerUri |
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 Google Tag Manager, 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, // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "id": string, "name": string, "uri": string // End of mutually exclusive fields. "quantity": integer, "conversionValue": number } |
| Campos | |
|---|---|
promotionIds[] |
Os IDs de promoção associados a este documento. No momento, esse campo é restrito a no máximo um ID. |
joined |
Apenas saída. Se o documento referenciado pode ser encontrado no repositório de dados. |
Um descritor obrigatório do
|
|
id |
O ID do recurso |
name |
O nome completo do recurso |
uri |
O URI |
| Fim dos campos mutuamente exclusivos. | |
quantity |
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 Obrigatório para eventos dos seguintes tipos:
|
conversionValue |
Opcional. O valor de conversão associado a este documento. Precisa ser definido se Por exemplo, um valor de 1.000 significa que 1.000 segundos foram gastos visualizando um documento para o tipo de conversão |
PanelInfo
Informações detalhadas do painel associadas a um evento do usuário.
| Representação JSON |
|---|
{
"panelId": string,
"displayName": string,
"documents": [
{
object ( |
| Campos | |
|---|---|
panelId |
Obrigatório. O ID do painel. |
displayName |
O nome de exibição do painel. |
documents[] |
Opcional. Os IDs de documento associados a este painel. |
panelPosition |
A posição ordenada do painel, se ele for mostrado ao usuário com outros painéis. Se definido, |
totalPanels |
O número total de painéis, incluindo este, exibidos ao usuário. Deve ser definido se |
SearchInfo
Informações detalhadas da pesquisa.
| Representação JSON |
|---|
{ "searchQuery": string, "orderBy": string, "offset": integer } |
| Campos | |
|---|---|
searchQuery |
A consulta de pesquisa do usuário. Consulte O valor precisa ser uma string codificada em UTF-8 com um limite de 5.000 caracteres. Caso contrário, um erro É necessário incluir pelo menos uma das seguintes propriedades: |
orderBy |
A ordem em que os produtos são retornados, se aplicável. Consulte O valor precisa ser uma string codificada em UTF-8 com um limite de 1.000 caracteres. Caso contrário, um erro Isso só pode ser definido para eventos |
offset |
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 Se esse campo for negativo, um Isso só pode ser definido para eventos |
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 |
O usuário final selecionou |
selectedPosition |
Posição |
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 |
Obrigatório. Código da moeda. Use o código ISO-4217 de três caracteres. |
transactionId |
O ID da transação com um limite de 128 caracteres. |
value |
Obrigatório. Valor total não nulo associado à transação. Esse valor pode incluir frete, tributos ou outros ajustes no valor total que você quer considerar. |
tax |
Todos os impostos associados à transação. |
cost |
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 |
O valor total dos descontos aplicados a esta transação. Esse valor precisa ser excluído de Por exemplo, se um usuário pagou o valor de Isso significa que o lucro é calculado da mesma forma, independente do valor do desconto, e que |
MediaInfo
Informações sobre eventos de usuário específicos da mídia.
| Representação JSON |
|---|
{ "mediaProgressDuration": string, "mediaProgressPercentage": number } |
| Campos | |
|---|---|
mediaProgressDuration |
O tempo de progresso da mídia em segundos, se aplicável. Por exemplo, se o usuário final tiver terminado 90 segundos de reprodução de um vídeo, então Duração em segundos com até nove dígitos fracionários, terminando em " |
mediaProgressPercentage |
O progresso da mídia deve ser calculado usando apenas o Este valor deve estar entre 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. |
Feedback
Informações sobre o feedback do usuário. Essas informações serão usadas para fins de métricas e registro.
| Representação JSON |
|---|
{ "feedbackType": enum ( |
| Campos | |
|---|---|
feedbackType |
Obrigatório. Indique se o usuário deu um feedback positivo ou negativo. Se o usuário der um feedback negativo, talvez haja mais detalhes. |
reasons[] |
Opcional. O motivo se o usuário der um polegar para baixo. |
comment |
Opcional. O comentário adicional do usuário no feedback se ele clicar em "Não gostei". |
conversationInfo |
As informações da conversa relacionada quando o usuário envia feedback. |
llmModelVersion |
A versão do modelo de LLM usada para gerar a resposta. |
feedbackSource |
Opcional. O componente da interface de onde vem o feedback do usuário, que pode ser GOOGLE_CONSOLE, GOOGLE_WIDGET, GOOGLE_WEBAPP. |
componentVersion |
Opcional. A versão do componente de onde este relatório está sendo enviado. |
dataTermsAccepted |
Opcional. Se o cliente aceitou os termos de uso de dados. |
FeedbackType
O tipo de feedback que o usuário dá.
| Tipos enumerados | |
|---|---|
FEEDBACK_TYPE_UNSPECIFIED |
Tipo de feedback não especificado. |
LIKE |
O usuário envia um feedback positivo. |
DISLIKE |
O usuário envia um feedback negativo. |
Motivo
O motivo pelo qual o usuário dá um feedback negativo.
| Tipos enumerados | |
|---|---|
REASON_UNSPECIFIED |
Motivo não especificado. |
INACCURATE_RESPONSE |
A resposta está incorreta. |
NOT_RELEVANT |
A resposta não é relevante. |
INCOMPREHENSIVE |
A resposta não é abrangente. |
OFFENSIVE_OR_UNSAFE |
A resposta é ofensiva ou perigosa. |
FORMAT_AND_STYLES |
A resposta não está bem formatada. |
BAD_CITATION |
A resposta não está bem associada à consulta. |
CANVAS_NOT_GENERATED |
A tela esperada não foi gerada para a resposta. |
CANVAS_QUALITY_BAD |
A tela gerada é de baixa qualidade (por exemplo, imprecisa, incompleta, mal formatada). |
CANVAS_EXPORT_FAILED |
Falha ao exportar a tela gerada (por exemplo, o download ou a ação de exportação externa não foi concluída). |
ConversationInfo
As informações da conversa, como o índice da pergunta e o nome da sessão.
| Representação JSON |
|---|
{
"questionIndex": integer,
"session": string,
"query": {
object ( |
| Campos | |
|---|---|
questionIndex |
O índice da entrada do usuário nas mensagens da conversa. |
session |
Nome da sessão recém-gerada ou continuada. |
query |
Obrigatório. A consulta de pesquisa do usuário. |
assistToken |
Opcional. O token que pode ser usado para buscar o registro do assistente. |
answerQueryToken |
Opcional. O token que pode ser usado para buscar o registro de respostas. |
FeedbackSource
Origem do feedback de acordo com a integração.
| Tipos enumerados | |
|---|---|
FEEDBACK_SOURCE_UNSPECIFIED |
Fonte de feedback não especificada. |
GOOGLE_CONSOLE |
A fonte do feedback é o Google Console. |
GOOGLE_WIDGET |
A fonte do feedback é o widget do Google. |
GOOGLE_WEBAPP |
A fonte do feedback é o aplicativo da Web do Google. |
GOOGLE_AGENTSPACE_MOBILE |
A fonte do feedback é o aplicativo Google AgentSpace Mobile. |
Métodos |
|
|---|---|
|
Grava um único evento de usuário a partir do navegador. |
|
Importação em massa de eventos de usuário. |
|
Exclui permanentemente todos os eventos de usuário especificados pelo filtro fornecido. |
|
Grava um único evento do usuário. |