Configurer les événements utilisateur

Cette page décrit l'objet User Event, répertorie les types d'événements utilisateur potentiels et fournit des exemples de données pour tous les types d'événements utilisateur.

Pour configurer vos événements utilisateur:

  1. Importer un historique d'événements utilisateur

  2. Enregistrez des événements utilisateur en direct.

  3. Taguez les événements utilisateur avec des entités.

  4. Marquez les événements utilisateur avec des jetons d'attribution.

Vertex AI Search pour le commerce utilise des événements utilisateur en temps réel pour générer des recommandations et des résultats de recherche. Lorsque vous importez des données, les recommandations et la recherche peuvent les utiliser. Vous n'avez donc pas besoin d'importer les mêmes événements deux fois si vous utilisez les deux services.

Pour obtenir de l'aide concernant l'enregistrement des événements utilisateur, consultez la page Enregistrer des événements utilisateur en temps réel.

Types d'événements utilisateur

Vous pouvez enregistrer plusieurs types d'événements utilisateur lorsque les utilisateurs parcourent votre site d'e-commerce :

Nom de l'événement utilisateur Action utilisateur
add-to-cart Permet d'ajouter le produit au panier.
category-page-view Permet d'afficher des pages spéciales, telles que des pages d'offres ou de promotions.
detail-page-view Permet d'afficher la page des détails du produit.
home-page-view Permet d'afficher la page d'accueil.
purchase-complete Permet de finaliser le paiement.
search Permet de rechercher dans le catalogue.
shopping-cart-page-view Permet d'afficher le panier.

Pour en savoir plus sur l'objet UserEvent, consultez la section UserEvent.

Priorité de types d'événements

Pour des résultats de meilleure qualité, nous vous recommandons d'enregistrer les événements utilisateur pour tous les types d'événements. Le tableau suivant décrit la priorité des différents types d'événements utilisateur. Vous devez consigner les événements utilisateur présentant la priorité la plus élevée pour obtenir des modèles de données de qualité.

Priorité Événements utilisateur
Obligatoire pour les expérimentations en direct initiales

add-to-cart

detail-page-view

purchase-complete

home-page-view (pour les recommandations)

search (pour la recherche)
Important pour améliorer la qualité du modèle de recommandations au fil du temps

category-page-view

search

shopping-cart-page-view

Exigences et bonnes pratiques relatives aux événements utilisateur

Les tableaux suivants affichent les exigences et les bonnes pratiques concernant les types d'événements utilisateur exploités par les recommandations et la recherche. Vérifiez que vos événements utilisateur répondent à ces exigences afin que Vertex AI Search pour le commerce puisse générer des résultats de qualité.

Cette section répertorie les éléments suivants :

Si vous utilisez des modèles de recommandation, consultez également la section Exigences relatives aux données du type de modèle, qui répertorie les exigences supplémentaires en fonction du type de modèle de recommandation et de l'objectif d'optimisation que vous prévoyez d'utiliser.

Vous pouvez consulter les métriques sur la qualité des données pour la recherche sur la page Qualité des données de la console Retail Search. Ces métriques indiquent les pourcentages de produits et d'événements utilisateur qui respectent les normes de qualité des données recommandées. Pour savoir comment afficher la qualité des données de recherche, consultez la section Débloquer les niveaux de performances de recherche.

Exigences concernant les événements utilisateur

Assurez-vous que vos événements utilisateur répondent aux exigences suivantes afin que Vertex AI Search pour le commerce puisse générer des résultats de qualité. Elles s'appliquent à la fois aux recommandations et à la recherche.

Type d'événement Exigence Impact
Tous les événements

N'incluez pas de données synthétiques ni de duplication d'événements.

Les événements synthétiques ou en double ont un impact négatif sur la qualité du modèle et empêchent souvent son entraînement. La duplication d'événements peut entraîner des valeurs de métriques incorrectes.

Incluez au moins 100 ID de visiteurs uniques pour chaque type d'événement ingéré.

Cela permet de s'assurer que Vertex AI Search pour le commerce dispose de suffisamment de données pour générer des résultats de qualité.

Les ID de visiteur doivent être formatés exactement de la même manière pour l'importation ou l'enregistrement des événements, ainsi que dans les requêtes API.

Utiliser un format cohérent pour les ID des visiteurs permet d'identifier correctement les tendances des visiteurs et de fournir des résultats de meilleure qualité en fonction du comportement des utilisateurs.

Les produits inclus dans les événements doivent exister dans votre catalogue de produits.

Le ratio d'événements non associés doit être le plus bas possible. Un ratio élevé peut avoir un impact négatif sur la qualité des recommandations ou des résultats de recherche.

Les données d'événements non associées ne sont pas utilisées pour entraîner des modèles. Toutefois, les événements non associés peuvent être associés ultérieurement, une fois que les produits associés ont été ingérés. Pour en savoir plus, consultez la section Rejoindre des événements utilisateur.

Certains événements utilisateur doivent avoir le même ID de visiteur.

Pour créer des historiques de séquences de comportement valides, Vertex AI Search for retail doit pouvoir afficher plusieurs événements avec le même ID de visiteur.

Par exemple, visitor123 a consulté cinq pages d'informations détaillées sur les produits, ajouté trois produits à son panier, puis acheté deux des cinq produits d'origine. Si tous ces événements fournissent le même ID de visiteur au format cohérent, Vertex AI Search for retail peut prendre en compte cette séquence de comportement dans ses modèles.

detail-page-view

Incluez un seul produit par événement.

Vous ne pouvez pas utiliser cet événement s'il n'existe aucun produit. Si plusieurs produits sont inclus, l'événement est incorrect et ne peut pas être utilisé.

add-to-cart

Incluez un seul produit par événement.

Si plusieurs produits sont inclus, l'événement est incorrect et ne peut pas être utilisé.

purchase-complete

Incluez purchase_transaction.revenue.

Les événements purchase-complete dont le champ revenue est manquant ne sont pas utilisés pour entraîner des modèles.

Incluez exactement un champ purchase_transaction.currency_code pour tous les événements d'achat.

Il n'existe pas de code de devise par défaut. Vous devez en fournir un.

Sans ce champ, les événements d'achat génèrent des métriques de revenus incorrectes.

Vérifiez que certains événements d'achat incluent plusieurs produits.

La présence d'événements d'achat avec plusieurs produits aide le modèle à apprendre les tendances d'achats associés.

Exigences spécifiques à Recommendations

Si vous utilisez des recommandations, assurez-vous que vos événements utilisateur répondent aux exigences suivantes.

Si vous utilisez des modèles de recommandation, consultez également la section Exigences relatives aux données du type de modèle, qui répertorie les exigences supplémentaires en fonction du type de modèle de recommandation et de l'objectif d'optimisation que vous prévoyez d'utiliser.

Type d'événement Exigence Impact
purchase-complete

Ne regroupez pas les paniers multi-articles en plusieurs événements d'achat. Ils doivent rester sous la forme d'événements d'achat uniques incluant plusieurs produits.

Cela permet de générer des modèles de co-achat valides.

Exigences concernant la recherche

Si vous utilisez la recherche, assurez-vous que vos événements utilisateur répondent aux exigences minimales suivantes pour obtenir des résultats.

Type d'événement Exigence Impact
search

searchQuery doit exister pour les événements de recherche et pageCategories pour les événements de navigation.

Le fait de ne pas inclure ce champ peut avoir un impact négatif important sur la qualité et les métriques des résultats de recherche.

L'ID de visiteur d'une requête de recherche doit correspondre à l'ID de visiteur envoyé dans les événements liés à cette requête de recherche.

S'ils ne correspondent pas, les événements sont incorrects et les métriques peuvent être incorrectes.

La liste des ID produit dans les événements de recherche doit correspondre à la liste des produits présentés à l'utilisateur dans son intégralité.

S'ils ne correspondent pas, l'impact négatif sur la qualité des résultats de recherche peut être important, et les métriques seront incorrectes.

Si la recherche utilise un filtre, le champ filter doit exister et être analysé correctement.

Si ce champ n'existe pas, Vertex AI Search for retail ne peut pas utiliser la partie filtrée des données, ce qui peut avoir un impact négatif sur la qualité des résultats de recherche.

Incluez le champ attribution_token pour relier d'autres événements aux événements de recherche.

Le fait de ne pas inclure de jeton d'attribution déclenchera une erreur dans Retail Search et aura un impact négatif important sur la qualité de la recherche et la précision des métriques.

Exigences d'optimisation pour le Réseau de Recherche

Pour permettre à la recherche d'optimiser automatiquement l'expérience de recherche en fonction des tendances générales des utilisateurs, importez les données suivantes.

Les événements doivent être mis en ligne au moins une fois par jour, avec un délai maximal de 24 heures.

Métrique "Événements" Volume/Fréquence des événements Description
Volume d'événements search 250 000 € au cours des 90 derniers jours

Au moins 250 000 événements au cours des 90 derniers jours sont obligatoires pour optimiser l'expérience de recherche en fonction des événements ingérés.

Nous vous recommandons d'importer des événements au moins une fois par jour pour maintenir une bonne qualité des données. Lors des importations d'événements historiques, assurez-vous que la distribution des données est biaisée vers l'horodatage le plus récent. Le nombre d'événements du dernier jour avec horodatage doit être égal ou supérieur au nombre moyen d'événements quotidiens.

Volume de detail-page-view attribuable à un événement search 500 000 € au cours des 30 derniers jours Au moins 500 000 événements sont obligatoires pour optimiser les résultats de recherche à l'aide d'événements utilisateur.
Nombre moyen d'événements detail-page-view attribuables à un événement search par produit 10 fois au cours des 30 derniers jours Obligatoire pour optimiser les résultats de recherche à l'aide des événements ingérés, sauf si les événements des 21 derniers jours sont importés.
Proportion d'événements search avec des filtres analysables 0,1 au cours des 30 derniers jours Recommandé pour optimiser l'ordre des attributs dynamiques dans la réponse de recherche.
Proportion de produits recherchés avec prix 0,95 au cours des 30 derniers jours Obligatoire pour optimiser les résultats de recherche à l'aide des événements ingérés.
Nombre moyen d'événements add-to-cart attribuables à un événement search par produit à prix 0,5 € au cours des 30 derniers jours Recommandé pour les résultats de recherche optimisés pour les revenus.
Nombre moyen d'événements purchase-complete attribuables à un événement search par produit avec prix consultable 0,5 € au cours des 30 derniers jours Recommandé pour les résultats de recherche optimisés pour les revenus.

Conditions requises pour la personnalisation de la recherche

La recherche nécessite les données suivantes pour personnaliser la recherche textuelle et les résultats de recherche de navigation pour vos utilisateurs en fonction de leur activité.

Une fois que vous avez importé les données suivantes, la recherche peut personnaliser automatiquement les résultats.

Métrique "Événements" Volume/Fréquence des événements Description
Volume d'événements search diffusés par la recherche 100 000 € au cours des 30 derniers jours

Au moins 100 000 événements diffusés par la recherche au cours des 30 derniers jours sont nécessaires pour fournir la personnalisation.

Les résultats de recherche ne sont pas mis en cache. Moins de 1% des 100 000 derniers événements utilisateur

Ne mettez pas en cache les résultats de recherche pour la recherche textuelle ni les recherches par navigation si vous prévoyez d'utiliser la personnalisation. Réutiliser les mêmes résultats pour tous les visiteurs empêche la recherche de fournir des résultats vraiment personnalisés à un utilisateur donné et risque d'exposer les données privées des utilisateurs. La personnalisation de la recherche est automatiquement désactivée si la mise en cache est détectée.

Si vous ne mettez en cache que les résultats de recherche, la recherche peut toujours personnaliser les résultats de navigation. À l'inverse, si vous ne mettez en cache que les résultats de navigation, la recherche peut toujours personnaliser les résultats de recherche de requêtes textuelles.

Correspondances entre l'ID de visiteur dans SearchRequests et les événements utilisateur Plus de 10% de correspondance pour les 100 000 derniers événements utilisateur Assurez-vous que l'espacement et la mise en forme de l'ID de visiteur correspondent entre SearchRequests et les événements utilisateur. Une mise en forme cohérente de l'ID de visiteur garantit que la recherche peut identifier correctement l'activité des utilisateurs.

Exemples et schémas de types d'événements utilisateur

Cette section fournit les formats de données pour chaque type d'événement compatible.

Des exemples sont fournis pour JavaScript Pixel et Tag Manager. Pour BigQuery, le schéma de table complet est fourni pour chaque type.

Pour tous les types d'événements utilisateur, le champ userId est facultatif. Les champs d'informations sur le produit (priceInfo et availability) sont facultatifs.

Remarques :

  • Le champ experimentIds n'est nécessaire que si vous effectuez un test A/B.
  • Le champ attributionToken est obligatoire pour Vertex AI Search pour le commerce uniquement. Il permet de mesurer les performances. Les événements predict, search et detail-page-view générés à partir de clics doivent disposer d'un jeton d'attribution pour lier les événements aux recherches ou recommandations générées.
  • Assurez-vous que tous vos événements utilisent une seule devise, en particulier si vous prévoyez d'utiliser la console Google Cloud pour obtenir des métriques de revenus. L'API Vertex AI Search pour le commerce n'est pas compatible avec l'utilisation de plusieurs devises par catalogue.

Pour en savoir plus sur l'objet User Event, consultez la documentation de référence de l'API UserEvent.

Ajout au panier

Les lignes suivantes présentent le format d'événement utilisateur add-to-cart.

Champs minimum requis pour l'objet add-to-cart

Les exemples suivants affichent uniquement les champs obligatoires du format d'événement utilisateur add-to-cart.

Lorsque vous importez des événements, vous devez spécifier l'horodatage dans le champ eventTime au format indiqué par RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si des champs supplémentaires sont utilisés. (Par exemple, si l'événement utilisateur est associé à une entité, veillez à spécifier le champ entity.) Pour en savoir plus sur chaque champ et savoir quand ils sont obligatoires, consultez la documentation de référence de l'API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "add-to-cart",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    },
    "quantity": { "value": product-quantity
  }]
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'add-to-cart',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          },
          'quantity': product-quantity
        }]
      }
    });
</script>

BigQuery

Il s'agit du schéma JSON complet pour ce type d'événement utilisateur. Spécifiez ce schéma lorsque vous créez des tables pour ce type d'événement utilisateur dans BigQuery.

Les modes des champs obligatoires sont définis sur REQUIRED ou REPEATED. Les modes des champs facultatifs sont définis sur NULLABLE.

Notez que le champ eventTime est requis pour l'importation d'événements avec BigQuery. eventTime est une chaîne avec un format d'horodatage. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Affichage de la page de catégorie

Les lignes suivantes présentent le format d'événement utilisateur category-page-view.

Champs minimum requis pour l'objet category-page-view

Les exemples suivants affichent uniquement les champs obligatoires du format d'événement utilisateur category-page-view.

Bien qu'une seule catégorie soit généralement associée à une page, le champ pageCategories accepte également une hiérarchie de catégories, que vous pouvez fournir sous forme de liste.

Lorsque vous importez des événements, vous devez spécifier l'horodatage dans le champ eventTime au format indiqué par RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si des champs supplémentaires sont utilisés. (Par exemple, si l'événement utilisateur est associé à une entité, veillez à spécifier le champ entity.) Pour en savoir plus sur chaque champ et savoir quand ils sont obligatoires, consultez la documentation de référence de l'API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "category-page-view",
  "visitorId": "visitor-id",
  "pageCategories": ["category1 > category2"]
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'category-page-view',
        'visitorId": 'visitor-id',
        // You can also define the user ID and visitor ID
        // directly on the Tag Manager tag.
        'pageCategories': ['category1 > category2']
      }
    });
</script>

BigQuery

Il s'agit du schéma JSON complet pour ce type d'événement utilisateur. Spécifiez ce schéma lorsque vous créez des tables pour ce type d'événement utilisateur dans BigQuery.

Les modes des champs obligatoires sont définis sur REQUIRED ou REPEATED. Les modes des champs facultatifs sont définis sur NULLABLE.

Notez que le champ eventTime est requis pour l'importation d'événements avec BigQuery. eventTime est une chaîne avec un format d'horodatage. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Affichage de la page des détails

Les lignes suivantes présentent le format de données d'événement utilisateur detail-page-view.

Champs minimum requis pour l'objet detail-page-view

Les exemples suivants affichent uniquement les champs obligatoires du format d'événement utilisateur detail-page-view.

Dans la plupart des cas, productDetails contient les détails du produit associé, sauf si plusieurs articles sont vendus ensemble au sein d'un lot.

Lorsque vous importez des événements, vous devez spécifier l'horodatage dans le champ eventTime au format indiqué par RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si des champs supplémentaires sont utilisés. (Par exemple, si l'événement utilisateur est associé à une entité, veillez à spécifier le champ entity.) Pour en savoir plus sur chaque champ et savoir quand ils sont obligatoires, consultez la documentation de référence de l'API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "detail-page-view",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    }
  }]
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'detail-page-view',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID directly on
        // the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          }
        }]
      }
    });
</script>

BigQuery

Il s'agit du schéma JSON complet pour ce type d'événement utilisateur. Spécifiez ce schéma lorsque vous créez des tables pour ce type d'événement utilisateur dans BigQuery.

Les modes des champs obligatoires sont définis sur REQUIRED ou REPEATED. Les modes des champs facultatifs sont définis sur NULLABLE.

Notez que le champ eventTime est requis pour l'importation d'événements avec BigQuery. eventTime est une chaîne avec un format d'horodatage. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Affichage de la page d'accueil

Les lignes suivantes présentent le format d'événement utilisateur home-page-view.

Champs minimum requis pour l'objet home-page-view

Les exemples suivants affichent uniquement les champs obligatoires du format d'événement utilisateur home-page-view.

Lorsque vous importez des événements, vous devez spécifier l'horodatage dans le champ eventTime au format indiqué par RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si des champs supplémentaires sont utilisés. (Par exemple, si l'événement utilisateur est associé à une entité, veillez à spécifier le champ entity.) Pour en savoir plus sur chaque champ et savoir quand ils sont obligatoires, consultez la documentation de référence de l'API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "home-page-view",
  "visitorId": "visitor-id",
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'home-page-view',
        'visitorId': 'visitor-id'
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
      }
    });
</script>

BigQuery

Il s'agit du schéma JSON complet pour ce type d'événement utilisateur. Spécifiez ce schéma lorsque vous créez des tables pour ce type d'événement utilisateur dans BigQuery.

Les modes des champs obligatoires sont définis sur REQUIRED ou REPEATED. Les modes des champs facultatifs sont définis sur NULLABLE.

Notez que le champ eventTime est requis pour l'importation d'événements avec BigQuery. eventTime est une chaîne avec un format d'horodatage. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Achat terminé

Les lignes suivantes présentent le format de données d'événement utilisateur purchase-complete.

Champs minimum requis pour l'objet purchase-complete

Les exemples suivants affichent uniquement les champs obligatoires du format d'événement utilisateur purchase-complete.

Lorsque vous importez des événements, vous devez spécifier l'horodatage dans le champ eventTime au format indiqué par RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si des champs supplémentaires sont utilisés. (Par exemple, si l'événement utilisateur est associé à une entité, veillez à spécifier le champ entity.) Pour en savoir plus sur chaque champ et savoir quand ils sont obligatoires, consultez la documentation de référence de l'API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "purchase-complete",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    },
    "quantity": product-quantity
  }],
  "purchaseTransaction": {
    "revenue": revenue,
    "currencyCode": "currency-code"
  }
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'purchase-complete',
        'visitorId': 'visitor-id',
        // You can also define the visitor id directly on
        // the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          },
          'quantity': product-quantity
        }],
        'purchaseTransaction': {
          'revenue': revenue,
          'currencyCode': 'currency-code'
        }
      }
    });
</script>

BigQuery

Il s'agit du schéma JSON complet pour ce type d'événement utilisateur. Spécifiez ce schéma lorsque vous créez des tables pour ce type d'événement utilisateur dans BigQuery.

Les modes des champs obligatoires sont définis sur REQUIRED ou REPEATED. Les modes des champs facultatifs sont définis sur NULLABLE.

Notez que le champ eventTime est requis pour l'importation d'événements avec BigQuery. eventTime est une chaîne avec un format d'horodatage. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         },
         {
           "name": "priceInfo",
           "type": "RECORD",
           "mode": "NULLABLE",
           "fields": [
             {
               "name": "price",
               "type": "FLOAT",
               "mode": "REQUIRED"
             },
             {
               "name": "originalPrice",
               "type": "FLOAT",
               "mode": "NULLABLE"
             },
             {
               "name": "currencyCode",
               "type": "STRING",
               "mode": "REQUIRED"
             },
             {
               "name": "cost",
               "type": "FLOAT",
               "mode": "NULLABLE"
             }
           ]
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "purchaseTransaction",
   "type": "RECORD",
   "mode": "REQUIRED",
   "fields": [
     {
       "name": "id",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "revenue",
       "type": "FLOAT",
       "mode": "REQUIRED"
     },
     {
       "name": "tax",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "cost",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "currencyCode",
       "type": "STRING",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Les lignes suivantes présentent le format d'événement utilisateur search.

Champs minimum requis pour l'objet search

Voici les champs obligatoires minimum pour que Vertex AI Search pour le commerce fonctionne:

  • Pour renvoyer une liste de résultats de recherche, Vertex AI Search pour le commerce nécessite à la fois searchQuery et productDetails:

    • searchQuery est lu à partir du paramètre search_term ou des événements view_search_results.
    • productDetails est lu à partir du paramètre items de l'événement view_item_list. Elle doit inclure la liste des ID produit présentés à l'utilisateur final sur la page des résultats de recherche.

  • Vous devez renseigner au moins l'un des champs searchQuery ou pageCategories.

Les exemples suivants affichent uniquement les champs obligatoires du format d'événement utilisateur search.

Lorsque vous importez des événements, vous devez spécifier l'horodatage dans le champ eventTime au format indiqué par RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si des champs supplémentaires sont utilisés. (Par exemple, si l'événement utilisateur est associé à une entité, veillez à spécifier le champ entity.) Pour en savoir plus sur chaque champ et savoir quand ils sont obligatoires, consultez la documentation de référence de l'API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "search",
  "visitorId": "visitor-id",
  "searchQuery": "search-query",
  "pageCategories": ["category1 > category2"],
  "productDetails": [
    {
      "product": {
        "id": "product-id1"
      }
    }, {
      "product": {
        "id": "product-id2"
      }
    }
  ]
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'search',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'searchQuery': 'search-query',
        'pageCategories': ['category1 > category2'],
        'productDetails': [
          {
            'product': {
              'id': 'product-id1'
            }
          }, {
            'product': {
              'id': 'product-id2'
            }
          }
        ]
      }
    });
</script>

BigQuery

Il s'agit du schéma JSON complet pour ce type d'événement utilisateur. Spécifiez ce schéma lorsque vous créez des tables pour ce type d'événement utilisateur dans BigQuery.

Les modes des champs obligatoires sont définis sur REQUIRED ou REPEATED. Les modes des champs facultatifs sont définis sur NULLABLE.

Notez que le champ eventTime est requis pour l'importation d'événements avec BigQuery. eventTime est une chaîne avec un format d'horodatage. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "searchQuery",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Saisie semi-automatique

Ce champ n'est obligatoire que pour les événements de recherche si vous souhaitez utiliser la saisie semi-automatique. Il n'est pas obligatoire pour la recherche.

Les exemples suivants montrent le champ completionDetail lorsqu'un utilisateur saisit "sh" et clique sur la deuxième suggestion, "shoes" (chaussures), dans la liste des suggestions pour déclencher un événement de recherche. Si l'utilisateur ne clique sur aucune suggestion, le champ completionDetail reste vide.

eventType doit être "search".

completionAttributionToken est l'attributionToken de la réponse completeQuery.

selectedSuggestion doit être identique à searchQuery.

JavaScript Pixel

var user_event = {
  "eventType": "search",
  "visitorId": "visitor-id",
  "searchQuery": "search-query",
  "pageCategories": ["category1 > category2"],
  "productDetails": [
    {
      "product": {
        "id": "product-id1"
      }
    }, {
      "product": {
        "id": "product-id2"
      }
    }
  ]
  "completionDetail": {
    "completionAttributionToken": "completion_token",
    "selectedSuggestion": "search-query",
    "selectedPosition": completion_position
  }
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'search',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'searchQuery': 'search-query',
        'pageCategories': ['category1 > category2'],
        'productDetails': [
          {
            'product': {
              'id': 'product-id1'
            }
          }, {
            'product': {
              'id': 'product-id2'
            }
          }
        ]
        "completionDetail": {
          "completionAttributionToken": 'completion_token',
          "selectedSuggestion": 'search-query',
          "selectedPosition": completion_position
        }
      }
    });
</script>

BigQuery

Il s'agit du schéma JSON complet pour ce type d'événement utilisateur. Spécifiez ce schéma lorsque vous créez des tables pour ce type d'événement utilisateur dans BigQuery.

Les modes des champs obligatoires sont définis sur REQUIRED ou REPEATED. Les modes des champs facultatifs sont définis sur NULLABLE.

Notez que le champ eventTime est requis pour l'importation d'événements avec BigQuery. eventTime est une chaîne avec un format d'horodatage. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "searchQuery",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "completionDetail",
   "type": "RECORD"
   "mode": "NULLABLE"
   "fields": [
     {
       "name": "completionAttributionToken",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "selectedSuggestion",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "selectedPosition",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
    ]
 }
]

Affichage de la page du panier

Les lignes suivantes présentent le format de données d'événement utilisateur shopping-cart-page-view.

Champs minimum requis pour l'objet shopping-cart-page-view

Les exemples suivants affichent uniquement les champs obligatoires du format d'événement utilisateur shopping-cart-page-view.

Spécifiez l'objet productDetails, sauf si le panier est vide.

Lorsque vous importez des événements, vous devez spécifier l'horodatage dans le champ eventTime au format indiqué par RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si des champs supplémentaires sont utilisés. (Par exemple, si l'événement utilisateur est associé à une entité, veillez à spécifier le champ entity.) Pour en savoir plus sur chaque champ et savoir quand ils sont obligatoires, consultez la documentation de référence de l'API UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "shopping-cart-page-view",
  "visitorId": "visitor-id
  "cartId": "cart-id",
  "productDetails": [{
    "product": {
       "id": "product-id"
     },
     {
       "id": "product-id"
     }
   }]
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'shopping-cart-page-view',
        'visitorId': 'visitor-id'
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'cartId': 'cart-id',
        'productDetails': [{
          'product': {
            'id': 'product-id'
           },
           {
             'id': 'product-id'
           }
         }]
      }
    });
</script>

BigQuery

Il s'agit du schéma JSON complet pour ce type d'événement utilisateur. Spécifiez ce schéma lorsque vous créez des tables pour ce type d'événement utilisateur dans BigQuery.

Les modes des champs obligatoires sont définis sur REQUIRED ou REPEATED. Les modes des champs facultatifs sont définis sur NULLABLE.

Notez que le champ eventTime est requis pour l'importation d'événements avec BigQuery. eventTime est une chaîne avec un format d'horodatage. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Champs d'événement utilisateur Google Analytics 4

Le tableau suivant montre comment les champs d'événement utilisateur Google Analytics 4 sont mappés sur les champs Vertex AI Search for retail.

Avant d'importer ou d'enregistrer des événements utilisateur à partir de Google Analytics 4, assurez-vous que vos événements utilisateur Google Analytics 4 utilisent les champs suivants afin que Vertex AI Search for retail puisse intégrer correctement vos données.

Google Analytics 4 Commerce
ecommerce.purchase_revenue purchaseTransaction.revenue
event_name eventType
event_timestamp eventTime
items.item_id productDetails.product.id
items.price productDetails.product.priceInfo.price
items.quantity productDetails.quantity
Clé:
event_params.key définie sur "currency"

Valeur:
event_params.value.string_value		 productDetails.product.priceInfo.currencyCode
Clé:
event_params.key définie sur "currency"

Valeur:
event_params.value.string_value		 purchaseTransaction.currencyCode
Clé:
event_params.key définie sur "search_term"

Valeur:
event_params.value.string_value		 searchQuery
user_id userInfo.userId
user_pseudo_id visitorId

Attributs personnalisés

Vous pouvez intégrer des attributs et des fonctionnalités personnalisés supplémentaires pour les événements utilisateur. Vous pouvez ainsi améliorer les recommandations de vos utilisateurs lorsque vous utilisez des recommandations. Pour ajouter des attributs personnalisés, utilisez attributes lorsque vous enregistrez un événement utilisateur.

Si vous fournissez des attributs personnalisés pour les événements utilisateur ingérés, il est important de les inclure é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 les événements fournis avec les requêtes de prédiction. Cela permet d'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.

Vous pouvez fournir des valeurs de texte personnalisées à l'aide du champ text ou des valeurs numériques personnalisées à l'aide du champ number.

Par exemple, voici la section attributes d'une requête d'enregistrement d'un événement utilisateur :

"attributes": {
  "user_age": {"text": ["teen", "young adult"]},
  "user_location": {"text": ["CA"]}
}

À propos des informations utilisateur

visitorId représente l'identifiant d'utilisateur unique et est requis lorsque vous enregistrez un événement utilisateur.

Les informations sur les utilisateurs (UserInfo) incluses lorsque vous enregistrez un événement utilisateur contiennent la valeur visitorId et, le cas échéant, la valeur userId. userId est facultatif et peut être utilisé comme identifiant unique et persistant pour un utilisateur sur tous les appareils, chaque fois que ce dernier se connecte à votre site. Lorsque vous enregistrez le userId d'un utilisateur, Vertex AI Search pour le commerce peut générer des résultats plus personnalisés pour un utilisateur sur plusieurs appareils, tels qu'un appareil mobile et un navigateur Web.

À propos de l'horodatage

Lorsque vous enregistrez un événement utilisateur, veillez à inclure un horodatage précis de l'événement. Des codes temporels précis permettent de s'assurer que les événements sont stockés dans le bon ordre. Les horodatages sont enregistrés automatiquement pour les événements collectés à l'aide de Tag Manager et du pixel JavaScript. Lorsque vous importez des événements, vous devez spécifier l'horodatage dans le champ eventTime au format indiqué par RFC 3339.

Étape suivante