Ce document concerne Recommendations AI, Retail Search et la nouvelle console Retail.

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

L'API Retail 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 dans l'API Retail, Recommendations AI et Retail Search peuvent utiliser ces données. Vous n'avez donc pas besoin d'importer les mêmes événements deux fois si vous utilisez les deux services.

Pour savoir comment enregistrer des événements utilisateur, consultez 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 Recommendations AI)

search (pour Retail Search)

Important pour améliorer la qualité du modèle Recommendations AI 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 Recommendations AI et Retail Search. Vérifiez que vos événements utilisateur répondent à ces exigences afin que l'API Retail puisse générer des résultats de qualité.

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

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.

Vous pouvez également afficher les métriques de qualité des données dans le panneau Qualité des données de la page Données de la console Retail. Ces métriques indiquent les pourcentages de produits et d'événements utilisateur répondant aux normes recommandées de qualité des données. Pour en savoir plus sur la manière d'afficher la qualité des données, consultez la page Métriques sur la qualité des données.

Exigences de l'API Retail

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é. Celles-ci s'appliquent à Recommendations AI et à Retail Search.

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.

Exigences spécifiques à Recommendations AI

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

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
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 spécifiques à Retail Search

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

Type d'événement Exigence Impact
search

search_query doit exister pour les événements de recherche (à l'exception des é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, l'API 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 de recherche a un impact très négatif sur la qualité de la recherche et la précision des métriques.

Exigences relatives aux objectifs de recherche

Vérifiez que vous répondez aux exigences minimales de données pour optimiser automatiquement l'expérience de recherche en fonction des événements ingérés. Les événements doivent être importés 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 des événements "search" 2 000 000 de messages au cours des 90 derniers jours L'ingestion de 2 000 000 d'événements search sur 90 jours est recommandée pour obtenir des analyses de qualité des données plus détaillées. Au moins deux millions d'événements survenus au cours des 90 derniers jours sont requis pour optimiser l'expérience de recherche en fonction des événements ingérés.
Volume de detail-page-view imputable à un événement search 500 000 au cours des 30 derniers jours Au moins 500 000 événements sont requis pour optimiser les résultats de recherche en utilisant des événements utilisateur.
Nombre moyen d'événements detail-page-view attribuables à un événement search par produit 10 au cours des 30 derniers jours Obligatoire pour optimiser les résultats de recherche à l'aide des événements ingérés, sauf s'ils sont importés au cours des 21 derniers jours.
Proportion d'événements search avec des filtres analysables 0,1 au cours des 30 derniers jours Recommandé pour un bon modèle d'attributs dynamiques.
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 prix 0,5 au cours des 30 derniers jours Recommandé pour les résultats de recherche optimisés en termes de revenus.
Nombre moyen d'événements purchase-complete pouvant être attribués à un événement search par produit auquel vous pouvez faire une recherche dans le prix 0,5 au cours des 30 derniers jours Recommandé pour les résultats de recherche optimisés en termes de revenus.

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 avec l'API Retail.

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 facultatif. Il permet de mesurer les performances. Les événements predict, search et detail-page-view générés à partir de clics sur l'API Retail doivent disposer d'un jeton d'attribution pour lier les événements aux recherches ou recommandations générées.
  • Assurez-vous que vos événements utilisent tous une seule devise, en particulier si vous prévoyez d'utiliser Google Cloud Console pour obtenir des métriques sur les revenus. L'API Retail n'accepte pas l'utilisation de plusieurs devises par catalogue.

Pour en savoir plus sur l'objet "événement utilisateur", 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 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",
  "cartId": "cart-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.
        'cartId': 'cart-id',
        '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 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": "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.

Au moins l'un des champs searchQuery ou pageCategories doit être renseigné.

productDetails doit inclure la liste des ID produit présentés à l'utilisateur final sur la page des résultats de recherche.

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",
  "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"
}
]

Saisie semi-automatique

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

Les exemples suivants présentent le champ completionDetail lorsqu'un utilisateur saisit "&sht" et clique sur la deuxième suggestion, "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 le 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 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
  "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"
}
]

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 Recommendations AI. 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 utilisateur (UserInfo) incluses lorsque vous enregistrez un événement utilisateur contiennent la valeur visitorId et, si disponible, la valeur userId. userId est facultatif et peut être utilisé comme identifiant unique et persistant d'un utilisateur sur plusieurs appareils chaque fois qu'il se connecte à votre site. Lorsque vous enregistrez l'ID userId pour un utilisateur, Retail API 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 horodatages précis permettent de s'assurer que l'API Retail stocke 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