Cette documentation de Recommendations AI fait référence à la console Recommendations. Nous vous recommandons de passer à la console Retail et d'utiliser la documentation pour le commerce de détail, qui fournit des informations sur Recommendations AI, la console et sur Retail Search.

Si vous utilisez la version v1beta de Recommendations AI, migrez vers la version Retail API.

É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 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 recommandations 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

home-page-view

purchase-complete
Important pour améliorer la qualité des modèles au fil du temps

category-page-view

search

shopping-cart-page-view

Exigences et bonnes pratiques relatives aux événements utilisateur

Assurez-vous que vos événements utilisateur répondent aux exigences suivantes afin que l'API Retail puisse générer des résultats de qualité.

Si vous utilisez des modèles Recommendations AI, consultez également la section Exigences relatives aux données des événements utilisateur, 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
Tous les événements

N'incluez pas de duplication d'événements.

La duplication d'événements peut entraîner des valeurs de métriques incorrectes et avoir un impact négatif sur la qualité du modèle.

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

Cela permet de s'assurer que l'API Retail dispose de suffisamment de données pour générer des résultats de qualité.

Le champ Product.name est obligatoire pour tous les produits. Utilisez le nom de ressource complet du produit plutôt que l'ID produit, qui est le composant final du nom de la ressource.

Un événement qui inclut un produit sans champ Product.name ne peut pas être utilisé par l'API Retail.

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.

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.

Sans ce champ, les modèles d'optimisation des revenus ne seront pas disponibles.

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

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

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

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

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

Cette section spécifie les formats de données pour chaque type d'événement compatible avec Recommendations AI.

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 user-id est facultatif. Les champs d'informations sur les articles de catalogue (currencyCode, originalPrice, displayPrice et stockState) sont facultatifs. S'ils sont renseignés, ils remplacent la valeur du catalogue.

Remarques :

  • Le champ experimentIds n'est nécessaire que si vous effectuez un test A/B.
  • Le champ attribution-token est facultatif. Il permet de mesurer les performances des recommandations. En savoir plus
  • Assurez-vous que vos événements utilisent tous une seule devise, surtout si vous prévoyez d'utiliser Cloud Console pour obtenir des métriques sur vos revenus. L'API Retail n'accepte pas l'utilisation de plusieurs devises par catalogue.

Pour en savoir plus sur l'objet User Event, consultez la page UserEvents.

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 fournir l'horodatage dans le champ eventTime au format spécifié par la norme RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si d'autres champs sont utilisés. Pour en savoir plus sur chaque champ et connaître les cas où 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": 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": "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"
 }
]
}
]

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 fournir l'horodatage dans le champ eventTime au format spécifié par la norme RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si d'autres champs sont utilisés. Pour en savoir plus sur chaque champ et connaître les cas où 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 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": "pageCategories",
"type": "STRING",
"mode": "REPEATED"
}
]

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 fournir l'horodatage dans le champ eventTime au format spécifié par la norme RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si d'autres champs sont utilisés. Pour en savoir plus sur chaque champ et connaître les cas où 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": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
 {
   "name": "product",
   "type": "RECORD",
   "mode": "REQUIRED",
   "fields": [
     {
       "name": "id",
       "type": "STRING",
       "mode": "REQUIRED"
     }
   ]
 }
]
}
]

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 fournir l'horodatage dans le champ eventTime au format spécifié par la norme RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si d'autres champs sont utilisés. Pour en savoir plus sur chaque champ et connaître les cas où 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"
}
]

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 fournir l'horodatage dans le champ eventTime au format spécifié par la norme RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si d'autres champs sont utilisés. Pour en savoir plus sur chaque champ et connaître les cas où 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": "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": "purchaseTransaction",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
 {
   "name": "revenue",
   "type": "FLOAT",
   "mode": "REQUIRED"
 },
 {
   "name": "currencyCode",
   "type": "STRING",
   "mode": "REQUIRED"
 }
]
}
]

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

Champs minimum requis pour l'objet search

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

Le champ searchQuery est obligatoire.

Lorsque vous importez des événements, vous devez fournir l'horodatage dans le champ eventTime au format spécifié par la norme RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si d'autres champs sont utilisés. Pour en savoir plus sur chaque champ et connaître les cas où 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"
};

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'
      }
    });
</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": "searchQuery",
"type": "STRING",
"mode": "NULLABLE"
}
]

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 fournir l'horodatage dans le champ eventTime au format spécifié par la norme RFC 3339.

D'autres champs peuvent être requis en fonction de la méthode d'API utilisée ou si d'autres champs sont utilisés. Pour en savoir plus sur chaque champ et connaître les cas où 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
  "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.
        '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"
}
]

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. 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. Le format des attributs personnalisés doit être cohérent entre les événements importés et les événements fournis avec des requêtes de prédiction. L'API Retail peut ainsi utiliser ces attributs personnalisés lors de l'entraînement des modèles et des prédictions de diffusion, ce qui permet d'améliorer la qualité des recommandations.

Vous pouvez fournir des valeurs textuelles 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 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, Recommendations AI peut générer des recommandations basées sur les produits consultés par l'utilisateur sur plusieurs appareils, tels que des appareils mobiles 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 horodatages précis permettent à Recommendations AI de stocker les événements 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.

Étapes suivantes