REST Resource: projects.locations.dataStores.userEvents

Ressource : UserEvent

UserEvent capture toutes les informations de métadonnées dont l'API Discovery Engine a besoin pour connaître la façon dont les utilisateurs finaux interagissent avec votre site Web.

Représentation 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)
    }
  ]
}
Champs
eventType

string

Obligatoire. Type d'événement utilisateur. Les valeurs autorisées sont les suivantes :

Valeurs génériques :

  • search : recherchez des documents.
  • view-item : vue détaillée d'une page d'un document.
  • view-item-list : vue d'un panneau ou liste ordonnée de documents.
  • view-home-page : vue de la page d'accueil.
  • view-category-page : vue d'une page de catégorie, par exemple Accueil > Hommes > Jeans

Valeurs liées au commerce :

  • add-to-cart : ajouter un ou plusieurs articles au panier, par exemple dans une boutique en ligne
  • purchase : acheter un ou plusieurs articles

Valeurs liées aux médias :

  • media-play : démarrer/reprendre la lecture d'une vidéo, d'un titre, etc.
  • media-complete : la vidéo, le titre, etc. sont terminés ou ont été arrêtés à mi-parcours.

Valeur de conversion personnalisée :

  • conversion : événement de conversion défini par le client.
conversionType

string

Facultatif. Type de conversion.

Obligatoire si UserEvent.event_type est défini sur conversion. Il s'agit d'un nom de conversion défini par le client, en lettres minuscules ou en chiffres séparés par un tiret ("-"), par exemple "watch", "good-visit", etc.

Ne définissez pas le champ si UserEvent.event_type n'est pas conversion. Cela combine l'événement de conversion personnalisé avec des événements prédéfinis tels que search, view-item, etc.
userPseudoId

string

Obligatoire. Identifiant unique permettant d'effectuer le suivi des visiteurs.

Par exemple, cela peut être implémenté avec un cookie HTTP, qui doit pouvoir identifier de manière unique un visiteur sur un seul appareil. Cet identifiant unique ne doit pas changer si le visiteur se connecte ou se déconnecte du site Web.

Ne définissez pas le champ sur le même ID fixe pour différents utilisateurs. L'historique des événements de ces utilisateurs est alors mélangé, ce qui dégrade la qualité du modèle.

Le champ doit être une chaîne encodée au format UTF-8 et ne doit pas dépasser 128 caractères. Dans le cas contraire, une erreur INVALID_ARGUMENT est renvoyée.

Ce champ ne doit pas contenir d'informations permettant d'identifier personnellement l'utilisateur ni de données utilisateur. Nous vous recommandons d'utiliser l'ID client Google Analytics pour ce champ.
engine

string

Nom de ressource Engine au format projects/{project}/locations/{location}/collections/{collectionId}/engines/{engineId}.

Facultatif. Obligatoire uniquement pour les événements utilisateur produits par Engine. Par exemple, les événements utilisateur provenant de la recherche mixte.
dataStore

string

Nom complet de la ressource DataStore, au format projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}.

Facultatif. Ce paramètre n'est obligatoire que pour les événements utilisateur dont le data store ne peut pas être déterminé par UserEvent.engine ou UserEvent.documents. Si le data store est défini dans le parent des requêtes d'écriture/d'importation/de collecte d'événements utilisateur, ce champ peut être omis.
eventTime

string (Timestamp format)

Obligatoire uniquement pour la méthode UserEventService.ImportUserEvents. Code temporel de l'événement utilisateur.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
userInfo

object (UserInfo)

Informations sur l'utilisateur final.
directUserRequest

boolean

Doit être défini sur "true" si la demande est effectuée directement par l'utilisateur final. Dans ce cas, UserEvent.user_info.user_agent peut être renseigné à partir de la requête HTTP.

Ce signalement ne doit être défini que si la requête API est effectuée directement par l'utilisateur final, par exemple à partir d'une application mobile (et non si une passerelle ou un serveur traite et envoie les événements utilisateur).

Il ne doit pas être défini lorsque vous utilisez la balise JavaScript dans UserEventService.CollectUserEvent.
sessionId

string

Identifiant unique permettant de suivre une session de visiteur. La longueur est limitée à 128 octets. Une session est une agrégation du comportement d'un utilisateur final sur une période donnée.

Voici une recommandation générale pour renseigner l'ID de session :

  1. Si l'utilisateur n'a aucune activité pendant 30 minutes, un nouvel ID de session doit lui être attribué.
  2. L'ID de session doit être unique pour chaque utilisateur. Nous vous suggérons d'utiliser un UUID ou d'ajouter UserEvent.user_pseudo_id comme préfixe.
pageInfo

object (PageInfo)

Métadonnées de la page, telles que les catégories et d'autres informations essentielles pour certains types d'événements, comme view-category-page.
attributionToken

string

Jeton permettant d'attribuer une réponse d'API à une ou plusieurs actions utilisateur pour déclencher l'événement.

Vivement recommandé pour les événements utilisateur résultant de RecommendationService.Recommend. Ce champ permet d'attribuer précisément les performances du modèle de recommandation.

La valeur doit être l'une des suivantes :

Ce jeton nous permet d'attribuer précisément une page vue ou une conversion à l'événement et à la réponse de prédiction spécifique contenant le produit sur lequel l'utilisateur a cliqué ou qu'il a acheté. Si l'utilisateur clique sur le produit K dans les résultats de recommandation, transmettez RecommendResponse.attribution_token en tant que paramètre d'URL à la page du produit K. Lorsque vous enregistrez des événements sur la page du produit K, consignez le RecommendResponse.attribution_token dans ce champ.
filter

string

La syntaxe des filtres consiste en un langage d'expression permettant de construire un prédicat à partir d'un ou de plusieurs champs des documents filtrés.

Par exemple, pour les événements search, le SearchRequest associé peut contenir une expression de filtre dans SearchRequest.filter conforme à https://google.aip.dev/160#filtering.

De même, pour les événements view-item-list générés à partir d'un RecommendRequest, ce champ peut être renseigné directement à partir de RecommendRequest.filter conformément à https://google.aip.dev/160#filtering.

La valeur doit être une chaîne encodée au format UTF-8 et ne doit pas dépasser 1 000 caractères. Dans le cas contraire, une erreur INVALID_ARGUMENT est renvoyée.
documents[]

object (DocumentInfo)

Liste des Document associés à cet événement utilisateur.

Ce champ est facultatif, sauf pour les types d'événements suivants :

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

Dans un événement search, ce champ représente les documents renvoyés à l'utilisateur final sur la page actuelle (il est possible que l'utilisateur final n'ait pas encore fini de parcourir toute la page). Lorsqu'une nouvelle page est renvoyée à l'utilisateur final, après pagination/filtrage/tri, même pour la même requête, un nouvel événement search avec un UserEvent.documents différent est souhaité.
panel

object (PanelInfo)

Métadonnées du panneau associées à cet événement utilisateur.
searchInfo

object (SearchInfo)

Détails SearchService.Search liés à l'événement.

Ce champ doit être défini pour l'événement search.
completionInfo

object (CompletionInfo)

Détails CompletionService.CompleteQuery liés à l'événement.

Ce champ doit être défini pour l'événement search lorsque la fonction de saisie semi-automatique est activée et que l'utilisateur clique sur une suggestion de recherche.
transactionInfo

object (TransactionInfo)

Métadonnées de transaction (le cas échéant) associées à cet événement utilisateur.
tagIds[]

string

Liste des identifiants des groupes de test indépendants auxquels appartient cet événement utilisateur. Il permet de faire la distinction entre les événements utilisateur associés à différentes configurations de test.
promotionIds[]

string

ID des promotions si l'événement y est associé. Actuellement, ce champ est limité à un ID maximum.
attributes

map (key: string, value: object)

Fonctionnalités d'événement utilisateur supplémentaires à inclure dans le modèle de recommandation. Ces attributs ne doivent PAS contenir de données nécessitant une analyse ou un traitement supplémentaires (par exemple, du code JSON ou d'autres encodages).

Si vous fournissez des attributs personnalisés pour les événements utilisateur ingérés, incluez-les également dans les événements utilisateur que vous associez aux requêtes de prédiction. La mise en forme des attributs personnalisés doit être cohérente entre les événements importés et ceux fournis avec les demandes de prédiction. L'API Discovery Engine peut ainsi utiliser ces attributs personnalisés lors de l'entraînement des modèles et de la diffusion des prédictions, ce qui contribue à améliorer la qualité des recommandations.

Ce champ doit répondre à tous les critères ci-dessous, sinon une erreur INVALID_ARGUMENT est renvoyée :

  • La clé doit être une chaîne encodée au format UTF-8 et ne doit pas dépasser 5 000 caractères.
  • Pour les attributs de texte, 400 valeurs maximum sont autorisées. Les valeurs vides ne sont pas autorisées. Chaque valeur doit être une chaîne encodée au format UTF-8 et ne doit pas dépasser 256 caractères.
  • Pour les attributs numériques, 400 valeurs maximum sont autorisées.

Pour les recommandations de produits, traffic_channel est un exemple d'informations utilisateur supplémentaires, qui indique comment un utilisateur accède au site. Les utilisateurs peuvent accéder au site directement, via la recherche Google ou par d'autres moyens.
attributes.text[]

string

Valeurs textuelles de cet attribut personnalisé. Par exemple, ["yellow", "green"] lorsque la clé est "color".

Une chaîne vide n'est pas autorisée. Dans le cas contraire, une erreur INVALID_ARGUMENT est renvoyée.

Vous ne devez définir qu'un seul élément CustomAttribute.text ou CustomAttribute.numbers. Dans le cas contraire, une erreur INVALID_ARGUMENT est renvoyée.
attributes.numbers[]

number

Valeurs numériques de cet attribut personnalisé. Par exemple, [2.3, 15.4] lorsque la clé est "lengths_cm".

Vous ne devez définir qu'un seul élément CustomAttribute.text ou CustomAttribute.numbers. Dans le cas contraire, une erreur INVALID_ARGUMENT est renvoyée.
mediaInfo

object (MediaInfo)

Informations spécifiques au média.
panels[]

object (PanelInfo)

Facultatif. Liste des panneaux associés à cet événement. Utilisé pour les données d'impression au niveau de la page.

PageInfo

Informations détaillées sur la page.

Représentation JSON 
{
  "pageviewId": string,
  "pageCategory": string,
  "uri": string,
  "referrerUri": string
}
Champs
pageviewId

string

Identifiant unique d'une vue de page Web.

Cette valeur doit rester la même pour tous les événements utilisateur déclenchés à partir de la même page vue. Par exemple, une vue de page d'informations sur un article peut déclencher plusieurs événements lorsque l'utilisateur parcourt la page. La propriété pageviewId doit rester la même pour tous ces événements afin qu'ils puissent être regroupés correctement.

Lorsque vous utilisez le reporting des événements côté client avec le pixel JavaScript et Google Tag Manager, cette valeur est renseignée automatiquement.
pageCategory

string

Catégorie la plus spécifique associée à une page de catégorie.

Pour représenter le chemin d'accès complet d'une catégorie, utilisez le signe ">" pour séparer les différentes hiérarchies. Si ">" fait partie du nom de la catégorie, remplacez-le par un ou plusieurs autres caractères.

Les pages de catégorie incluent des pages spéciales telles que les pages d'offres ou de promotions. Par exemple, une page d'offre spéciale peut avoir la hiérarchie de catégories suivante : "pageCategory" : "Sales > 2017 Black Friday Deals".

Obligatoire pour les événements view-category-page. Les autres types d'événements ne doivent pas définir ce champ. Dans le cas contraire, une erreur INVALID_ARGUMENT est renvoyée.
uri

string

URL complète (window.location.href) de la page actuelle de l'utilisateur.

Lorsque vous utilisez le reporting des événements côté client avec le pixel JavaScript et Google Tag Manager, cette valeur est renseignée automatiquement. La longueur ne doit pas dépasser 5 000 caractères.
referrerUri

string

URL de provenance de la page actuelle.

Lorsque vous utilisez le reporting des événements côté client avec le pixel JavaScript et Google Tag Manager, cette valeur est renseignée automatiquement. Toutefois, certaines restrictions de confidentialité du navigateur peuvent entraîner la suppression de ce champ.

DocumentInfo

Informations détaillées sur le document associées à un événement utilisateur.

Représentation 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
}
Champs
promotionIds[]

string

ID des promotions associées à ce document. Actuellement, ce champ est limité à un ID maximum.
joined

boolean

Uniquement en sortie. Indique si le document référencé se trouve dans le data store.

Champ d'union document_descriptor. Descripteur obligatoire de l'Document associé.

  • Si id est spécifié, les valeurs par défaut de {location}, {collection_id}, {data_store_id} et {branch_id} sont utilisées lors de l'annotation avec le document stocké.

  • Si name est spécifié, les valeurs fournies (valeurs par défaut autorisées) pour {location}, {collection_id}, {data_store_id} et {branch_id} sont utilisées lors de l'annotation avec le document stocké. document_descriptor ne peut être qu'un des éléments suivants :
id

string

ID de ressource Document.
name

string

Nom complet de la ressource Document, au format projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}/branches/{branchId}/documents/{documentId}
uri

string

URI Document : autorisé uniquement pour les datastores de site Web.
quantity

integer

Quantité du document associé à l'événement utilisateur. La valeur par défaut est 1.

Par exemple, ce champ est défini sur "2" si deux quantités du même document sont impliquées dans un événement add-to-cart.

Obligatoire pour les événements des types suivants :

  • add-to-cart
  • purchase
conversionValue

number

Facultatif. Valeur de conversion associée à ce document. Doit être défini si UserEvent.event_type est défini sur "conversion".

Par exemple, une valeur de 1 000 signifie que 1 000 secondes ont été passées à consulter un document pour le type de conversion watch.

PanelInfo

Informations détaillées sur le panneau associées à un événement utilisateur.

Représentation JSON 
{
  "panelId": string,
  "displayName": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panelPosition": integer,
  "totalPanels": integer
}
Champs
panelId

string

Obligatoire. ID du panneau.
displayName

string

Nom à afficher du panneau.
documents[]

object (DocumentInfo)

Facultatif. ID des documents associés à ce panneau.
panelPosition

integer

Position ordonnée du panneau, s'il est présenté à l'utilisateur avec d'autres panneaux. Si cette valeur est définie, totalPanels doit également l'être.
totalPanels

integer

Nombre total de panneaux affichés à l'utilisateur, y compris celui-ci. Doit être défini si panelPosition est défini.

SearchInfo

Informations détaillées sur la recherche.

Représentation JSON 
{
  "searchQuery": string,
  "orderBy": string,
  "offset": integer
}
Champs
searchQuery

string

Requête de recherche de l'utilisateur.

Pour en savoir plus, consultez SearchRequest.query.

La valeur doit être une chaîne encodée au format UTF-8 et ne doit pas dépasser 5 000 caractères. Dans le cas contraire, une erreur INVALID_ARGUMENT est renvoyée.

Au moins l'un des éléments searchQuery ou PageInfo.page_category est requis pour les événements search. Les autres types d'événements ne doivent pas définir ce champ. Dans le cas contraire, une erreur INVALID_ARGUMENT est renvoyée.
orderBy

string

Ordre dans lequel les produits sont renvoyés, le cas échéant.

Consultez SearchRequest.order_by pour obtenir la définition et la syntaxe.

La valeur doit être une chaîne encodée au format UTF-8 et ne doit pas dépasser 1 000 caractères. Dans le cas contraire, une erreur INVALID_ARGUMENT est renvoyée.

Cette option ne peut être définie que pour les événements search. Les autres types d'événements ne doivent pas définir ce champ. Dans le cas contraire, une erreur INVALID_ARGUMENT est renvoyée.
offset

integer

Valeur entière spécifiant le décalage actuel pour la pagination (emplacement de départ indexé sur 0, parmi les produits jugés pertinents par l'API).

Pour en savoir plus, consultez SearchRequest.offset.

Si ce champ est négatif, une erreur INVALID_ARGUMENT est renvoyée.

Cette option ne peut être définie que pour les événements search. Les autres types d'événements ne doivent pas définir ce champ. Dans le cas contraire, une erreur INVALID_ARGUMENT est renvoyée.

CompletionInfo

Informations détaillées sur la finalisation, y compris le jeton d'attribution de la finalisation et les informations sur la finalisation après clic.

Représentation JSON 
{
  "selectedSuggestion": string,
  "selectedPosition": integer
}
Champs
selectedSuggestion

string

L'utilisateur final CompleteQueryResponse.QuerySuggestion.suggestion a été sélectionné.
selectedPosition

integer

Position CompleteQueryResponse.QuerySuggestion.suggestion sélectionnée par l'utilisateur final, à partir de 0.

TransactionInfo

Une transaction représente l'intégralité de la transaction d'achat.

Représentation JSON 
{
  "currency": string,
  "transactionId": string,
  "value": number,
  "tax": number,
  "cost": number,
  "discountValue": number
}
Champs
currency

string

Obligatoire. Code de devise. Utilisez le code ISO-4217 à trois caractères.
transactionId

string

ID de la transaction (128 caractères maximum).
value

number

Obligatoire. Valeur totale non nulle associée à la transaction. Cette valeur peut inclure les frais de livraison, les taxes ou d'autres ajustements à la valeur totale que vous souhaitez inclure.
tax

number

Toutes les taxes associées à la transaction.
cost

number

Tous les coûts associés aux produits. Il peut s'agir de coûts de fabrication, de frais de port non supportés par l'utilisateur final ou de tout autre coût, de sorte que :
discountValue

number

Valeur totale des remises appliquées à cette transaction. Ce chiffre doit être exclu de TransactionInfo.value

Par exemple, si un utilisateur a payé un montant de TransactionInfo.value, la valeur nominale (avant remise) de la transaction correspond à la somme de TransactionInfo.value et TransactionInfo.discount_value.

Cela signifie que le bénéfice est calculé de la même manière, quelle que soit la valeur de la remise, et que TransactionInfo.discount_value peut être supérieur à TransactionInfo.value :

MediaInfo

Informations sur les événements utilisateur spécifiques aux médias.

Représentation JSON 
{
  "mediaProgressDuration": string,
  "mediaProgressPercentage": number
}
Champs
mediaProgressDuration

string (Duration format)

Le temps de progression du contenu multimédia en secondes, le cas échéant. Par exemple, si l'utilisateur final a regardé 90 secondes d'une vidéo, MediaInfo.media_progress_duration.seconds doit être défini sur 90.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"
mediaProgressPercentage

number

La progression du contenu multimédia ne doit être calculée qu'à l'aide de mediaProgressDuration par rapport à la durée totale du contenu multimédia.

Cette valeur doit être comprise entre [0, 1.0] inclus.

Si ce n'est pas une lecture ou si la progression ne peut pas être calculée (par exemple, une diffusion en direct en cours), ce champ doit être défini sur "non défini".

Méthodes

collect

 Écrit un seul événement utilisateur à partir du navigateur.

import

 Importation groupée d'événements utilisateur.

purge

 Supprime définitivement tous les événements utilisateur spécifiés par le filtre fourni.

write

 Écrit un seul événement utilisateur.