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

Enregistrer des événements utilisateur en temps réel

Cette page décrit comment enregistrer des événements utilisateur en temps réel. L'API Retail utilise des événements utilisateur en temps réel pour générer des recommandations et des résultats de recherche. Enregistrer autant d'événements utilisateur que possible avec des informations valides sur le produit augmente la qualité des résultats.

Les procédures d'enregistrement décrites sur cette page s'appliquent à Recommendations AI et à Retail Search. Une fois que vous avez enregistré des données dans l'API Retail, les deux services peuvent utiliser ces événements. Vous n'avez donc pas besoin d'importer les mêmes données deux fois si vous utilisez les deux services.

Pour en savoir plus sur les événements utilisateur, y compris les types d'événements utilisateur et des exemples JSON pour tous les types, consultez la page Événements utilisateur.

Vous pouvez enregistrer un événement utilisateur de plusieurs manières :

Vous trouverez ci-dessous des exemples d'enregistrement d'événement utilisateur de type detail-page-view. Pour les autres types d'événements, consultez la page Événements utilisateur.

Vous pouvez également importer l'historique des événements utilisateur. L'enregistrement d'une quantité suffisante de données utilisateur pour entraîner vos modèles peut prendre un temps considérable. Vous pouvez accélérer l'entraînement initial du modèle en important de façon groupée des données d'événements utilisateur issues d'événements antérieurs. Pour en savoir plus, consultez Importer des événements utilisateur historiques.

Si l'événement utilisateur que vous enregistrez est la première interaction d'un utilisateur avec un produit sur la base d'une recommandation ou de résultats de recherche fournis précédemment, l'inclusion d'un jeton d'attribution permet à l'API Retail de fournir métriques de performances. L'ajout d'un jeton d'attribution est facultatif, mais vivement recommandé. Pour en savoir plus sur l'utilisation des jetons d'attribution, consultez la section Jetons d'attribution.

Vous devez indiquer les ID de visiteur lorsque vous enregistrez des événements utilisateur. Pour en savoir plus sur les ID de visiteur et les ID utilisateur, consultez la page À propos des informations utilisateur.

Écrire des événements utilisateur

Ce tutoriel explique comment enregistrer des événements utilisateur à l'aide de la méthode userEvents.write.


Pour obtenir des conseils détaillés sur cette tâche directement dans l'éditeur Cloud Shell, cliquez sur Visite guidée :

Visite guidée


La procédure décrite dans les sections suivantes, est la même que si vous cliquez sur Visite guidée.

Avant de commencer

Avant d'enregistrer des événements utilisateur, vous devez avoir :

  • Un projet Google Cloud créé, avec l'authentification configurée.

  • Une clé API valide (pour JavaScript Pixel ou Tag Manager) ou un compte de service valide auquel le rôle Éditeur Retail est attribué si vous préférez utiliser l'API pour écrire directement.

    Pour plus d'informations, consultez la section Avant de commencer.

Remarques concernant l'importation d'événements

Cette section décrit les méthodes pouvant être utilisées pour l'importation par lot de votre historique d'événements utilisateur, les cas de figure dans lesquels vous pouvez les utiliser et certaines de leurs limitations.

Cloud Storage Description Importer des données au format JSON à partir de fichiers chargés dans un bucket Cloud Storage. Chaque fichier doit avoir une taille inférieure ou égale à 2 Go, et vous pouvez importer jusqu'à 100 fichiers à la fois. L'importation peut être effectuée à l'aide de Google Cloud Console ou de cURL. Utilise le format de données JSON Product, qui permet d'utiliser des attributs personnalisés.
Contexte d'utilisation Si vous avez besoin de charger des volumes de données importants en une seule étape.
Limites Si vos données se trouvent dans Google Analytics ou Merchant Center, elles ne peuvent être exportées que vers BigQuery et nécessitent donc une étape supplémentaire d'importation vers Cloud Storage.
BigQuery Description Importer des données à partir d'une table BigQuery précédemment chargée qui utilise le schéma Retail. Vous pouvez le faire via Google Cloud Console ou cURL.
Contexte d'utilisation Si vous appliquez également des fonctions analytiques ou un prétraitement des données d'événement avant l'importation.
Limites Nécessite l'étape supplémentaire de la création d'une table BigQuery mappée sur le schéma Retail. Si vous avez un volume élevé d'événements utilisateur, pensez également que BigQuery est une ressource moins coûteuse que Cloud Storage.
BigQuery avec Google Analytics 360 Description Importer des données préexistantes depuis Google Analytics vers Retail.
Contexte d'utilisation Si vous utilisez Google Analytics et que vous assurez le suivi des conversions pour les recommandations ou les recherches. Aucun mappage de schéma supplémentaire n'est requis.
Limites Seul un sous-ensemble d'attributs est disponible. Par conséquent, certaines fonctionnalités avancées de Retail ne peuvent pas être utilisées. Le suivi des impressions dans Google Analytics est requis si vous prévoyez d'utiliser Retail Search.
Importation intégrée Description Importer à l'aide d'un appel à la méthode userEvents.import
Contexte d'utilisation Si vous souhaitez améliorer la confidentialité de l'ensemble des processus d'authentification sur le backend et être en mesure d'effectuer une importation backend.
Limites Généralement plus complexe qu'une importation Web.

Bonnes pratiques pour l'enregistrement des événements utilisateur

L'API Retail nécessite des données de haute qualité pour générer des résultats de haute qualité. Des données incomplètes ou incorrectes affectent négativement la qualité de vos résultats.

Lorsque vous enregistrez des événements utilisateur, veillez à mettre en œuvre les bonnes pratiques suivantes :

  • Si vous enregistrez des événements utilisateur avant ou pendant l'importation de votre catalogue, réassociez tous les événements enregistrés avant la fin de l'importation.

    Vous pouvez importer le catalogue dans l'API Retail avant, après ou pendant l'enregistrement des événements utilisateur. Effectuer ces tâches en parallèle permet de gagner du temps si le catalogue est volumineux et qu'il y a de nombreux événements utilisateur. Une fois l'importation du catalogue terminée, vous devez utiliser l'API pour rejoindre les événements importés avant la fin de l'importation.

    Retail tente d'associer les événements utilisateur enregistrés aux métadonnées du catalogue de produits lors de la création de l'événement utilisateur. Seuls les événements correctement associés aux métadonnées sont utilisés pour l'entraînement. Par conséquent, veillez à bien réassocier tous les événements enregistrés avant l'importation complète du catalogue. Si un événement fait référence à un élément qui n'existe pas dans le catalogue, il est supprimé ou n'est pas associé aux produits appropriés. De même, si vous importez des événements utilisateur passés, le catalogue doit inclure tous les produits auxquels ils font référence. Vous pouvez marquer les produits plus anciens avec OUT_OF_STOCK plutôt que de les supprimer du catalogue.

  • Maintenez votre catalogue à jour.

    Lorsque vous enregistrez des événements utilisateur, le produit inclus dans l'événement utilisateur est connecté à votre catalogue actuel. Si vous enregistrez un événement pour un produit ne figurant pas dans le catalogue actuel, il ne peut pas être utilisé par l'API Retail pour entraîner vos modèles. Il s'agit d'un événement "non associé". Si vous avez enregistré des événements avant l'importation complète de votre catalogue, vous devez réassocier les événements enregistrés lors de l'importation. Le fait d'avoir quelques événements non associés est courant. Toutefois, si le pourcentage d'événements non associés atteint ou dépasse 5 % de votre nombre total d'événements utilisateur, vérifiez que votre catalogue est à jour, réassociez les événements enregistrés avant la mise à jour complète du catalogue, et tentez de trouver ce que entraîne la création d'événements non associés.

    Vous pouvez afficher les événements non associés en utilisant les filtres d'événements. En savoir plus

  • Fournissez autant d'informations que possible sur vos événements utilisateur.

    Chaque type d'événement utilisateur bénéficie d'un ensemble spécifique d'informations requises et acceptées. Pour en savoir plus, consultez la page Événements utilisateur.

  • Configurez des alertes pour savoir si les processus d'enregistrement des événements utilisateur subissent des interruptions.

  • Pour une importation groupée d'événements utilisateur, limitez la taille des données que vous importez.

    L'importation groupée d'événements utilisateur peut prendre jusqu'à 24 heures.

    La taille de chaque fichier doit être inférieure ou égale à 2 Go. Vous pouvez inclure 100 fichiers au maximum dans une même requête d'importation. Une approche possible consiste à importer les événements utilisateur un jour à la fois.

  • Après une importation groupée, consultez vos rapports d'erreurs pour vous assurer que vos données ont été importées correctement.

  • Lorsque vous importez des données d'événement utilisateur, incluez un horodatage précis pour chaque événement utilisateur et évitez d'importer des événements utilisateur séquentiels avec des horodatages identiques.

    Indiquez l'horodatage dans le champ eventTime au format spécifié par la RFC 3339.

  • Si vous avez importé des événements utilisateur incorrects, contactez votre contact Retail pour savoir comment corriger le problème.

  • Dans la mesure du possible, utilisez des données d'événements utilisateur continues.

    Des périodes manquantes dans les données d'événements utilisateur peuvent réduire la qualité du modèle.

  • Utilisez un identifiant unique sécurisé pour assurer la confidentialité des informations de vente et protéger la vie privée des utilisateurs. Vous êtes responsable du masquage des informations personnelles (PII) telles que les adresses e-mail ou personnelles dans vos données.

Enregistrer des événements utilisateur avec un pixel JavaScript

L'exemple suivant enregistre un UserEvent detail-page-view à l'aide d'un pixel JavaScript.

<script type="text/javascript">
var user_event = {
  "eventType" : "detail-page-view",
  "visitorId": "visitor-id",
  "userInfo": {
      "userId": "user-id"
  },
  "attributionToken": "attribution-token",
  "experimentIds": "experiment-id",
  "productDetails": [
      {
        "product": {"id": "123"}
      }
  ]
};

var _gre = _gre || [];
// Credentials for project.
_gre.push(['apiKey', 'api-key']);
_gre.push(['logEvent', user_event]);
_gre.push(['projectId', 'project-id']);
_gre.push(['locationId', 'global']);
_gre.push(['catalogId', 'default_catalog']);

(function() {
  var gre = document.createElement('script'); gre.type = 'text/javascript'; gre.async = true;
  gre.src = 'https://www.gstatic.com/retail/v2_event.js';
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(gre, s);
})();

</script>

Si vous avez importé des événements utilisateur à l'aide de Google Analytics 360, définissez visitorID sur l'ID client Google Analytics. Notez que l'ID client Google Analytics n'est qu'une partie du nom complet du cookie _ga (par exemple, l'ID client 123456789.123456789 fait partie du cookie _ga GA1.3.123456789.123456789).

Pour en savoir plus sur l'obtention de l'ID client, consultez la documentation Google Analytics.

Voici un exemple abrégé qui explique le format de l'ID client dans un événement utilisateur. Remplacez "UA-XXXXXX-N" par votre ID de suivi Google Analytics.

<script type="text/javascript">
var tracker = ga.getByName('UA-XXXXXX-N');
var user_event = {
      "visitorId": tracker.get('clientId')
};
</script>

Enregistrer des événements utilisateur avec la méthode userEvents.write

Vous pouvez utiliser la méthode userEvents.write pour envoyer des événements utilisateur directement à l'API à partir de votre serveur backend.

Pour enregistrer des événements utilisateur, envoyez une requête POST à la méthode userEvents.write et fournissez le corps de requête approprié.

curl

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data "{
         'eventType': 'detail-page-view',
         'visitorId': 'visitor0',
         'eventTime': '2020-01-01T03:33:33.000001Z',
         'experimentIds': ['321'],
         'attributionToken': 'ABC',
         'attributes': {
            'example_text_attribute': {
              'text': ['text_1', 'text_2']
            },
            'example_number_attribute': {
               'numbers': [3.14, 42, 1.2345]
            }
         },
         'productDetails': [{
           'product': {
             'id': 'abc'
           }
          }],
         'userInfo': {
           'userId': 'abc',
           'ipAddress': '8.8.8.8',
           'userAgent': 'Mozilla/5.0',
           'directUserRequest': true
         },
         'uri': 'http://example',
         'referrerUri': 'http://example',
         'pageViewId': 'currentPageUri'
}" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:write"

Java

public static UserEvent writeUserEvents(UserEvent eventToWrite)
    throws IOException, InterruptedException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  WriteUserEventRequest request = WriteUserEventRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setUserEvent(eventToWrite)
      .build();

  UserEvent writtenUserEvent = userEventsClient.writeUserEvent(request);

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return writtenUserEvent;
}

Enregistrer des événements utilisateur avec Google Tag Manager

Tag Manager vous permet de gérer et de tester plusieurs tags sans apporter de modifications majeures au code côté serveur de votre site.

Certaines décisions prises lors de la configuration varient selon que vous utilisez Google Analytics ou l'e-commerce Google Analytics. Vous pouvez intégrer l'e-commerce Google Analytics à l'aide de Google Analytics 4 ou de l'e-commerce amélioré. La balise Cloud Retail est compatible avec les deux.

Ni l'e-commerce Google Analytics ni Google Analytics n'est requis. Si vous ne les utilisez pas, vous pouvez configurer Variable - E-commerce lorsque vous créez la balise Cloud Retail, ou insérer manuellement le code de la couche de données de votre site après la création de la balise.

L'e-commerce Google Analytics est une configuration supplémentaire pour Google Analytics qui transmet à Google Analytics les titres de produits, les ID, les prix, les détails des transactions et d'autres données d'e-commerce structurées. L'API Retail peut automatiquement utiliser la couche de données d'e-commerce Google Analytics. Si vous l'avez déjà configurée, la configuration peut être plus simple. Si vous n'avez pas configuré Google Analytics pour l'e-commerce pour Google Analytics, mais que vous souhaitez l'utiliser, consultez le guide du développeur GA4 ou le guide du développeur sur l'e-commerce amélioré.

Utilisez cette procédure unique pour configurer un tag Cloud Retail dans Tag Manager pour enregistrer des événements utilisateur.

Créer une variable d'ID de visiteur

L'API Retail utilise la valeur visitorId pour suivre les utilisateurs. visitorId est généralement un ID de session et est requis pour tous les événements. Configurez une variable qui définit les ID de session sur visitorId.

Si vous utilisez Google Analytics, vous pouvez utiliser l'ID de visiteur Google Analytics. Pour configurer ce paramètre, procédez comme suit pour remplacer la valeur d'ID de visiteur par le tag Cloud Retail. Cela mappe le cookie propriétaire "_ga" à une variable Tag Manager appelée "GA visitorId". Vous pouvez faire de même avec n'importe quel cookie d'ID de session (le cookie ne doit pas nécessairement provenir de Google Analytics).

Cette procédure suppose que vous utilisez Google Analytics. Si ce n'est pas le cas, vous pouvez utiliser un autre cookie ou une autre variable, ou obtenir l'ID de visiteur à partir de la couche de données cloud_retail.

Pour définir la valeur visitorID sur une variable du tag Cloud Retail, procédez comme suit :

  1. Dans Tag Manager, accédez à l'onglet Variables, puis cliquez sur Nouveau pour créer une variable définie par l'utilisateur.

  2. Attribuez un nom à la variable en haut de la boîte de dialogue, tel que "GA visitorId".

  3. Saisissez les paramètres de votre variable.

    Vous pouvez utiliser l'ID client ou l'ID de cookie pour définir la source des ID de visiteur. Utilisez toujours une source d'ID de visiteur cohérente lorsque vous ingérez des événements utilisateur historiques et en temps réel.

    ID client

    Dans Google Analytics 360 BigQuery, cette variable correspond au champ clientID dans le schéma d'exportation BigQuery dans Universal Analytics. Dans Google Analytics 4, cette variable correspond au champ user_pseudo_id dans le schéma d'exportation BigQuery dans Google Analytics 4.

    1. Définissez Type de variable sur JavaScript personnalisé.

    2. Saisissez le script suivant dans le champ JavaScript personnalisé.

      Remplacez "UA-XXXXXX-N" par votre ID de suivi Google Analytics. Pour trouver votre ID de suivi, consultez la section Qu'est-il arrivé à mon ID de suivi ? Pour en savoir plus sur l'obtention de l'ID client, consultez la documentation Google Analytics.

      function() {
       var tracker = ga.getByName('UA-XXXXXX-N');
       return tracker.get('clientID');
      }
      
    3. Cliquez sur Enregistrer pour enregistrer la variable.

    1. Choisissez le type de variable Cookie propriétaire.

    2. Dans le champ Nom du cookie, saisissez _ga.

    3. Cliquez sur Formater la valeur, sélectionnez Convertir non défini sur, puis saisissez "" (une chaîne vide).

    4. Cliquez sur Enregistrer pour enregistrer la variable.

      Cela a pour effet de mapper le cookie propriétaire "_ga" à une variable Tag Manager appelée "GA visitorId".

Ensuite, créez un tag Cloud Retail dans Tag Manager. Ce tag utilisera la variable d'ID visiteur que vous venez de créer.

Créer une balise Google Tag Manager

Configurez un tag dans Tag Manager pour envoyer des informations sur les événements utilisateur à l'API Retail.

  1. Connectez-vous à Tag Manager et sélectionnez le conteneur de votre site.

  2. Accédez à l'onglet Tags et cliquez sur Nouveau pour ajouter un tag.

  3. Attribuez un nom à votre tag en haut du panneau (l'espace réservé est une variable sans titre), par exemple "Retail".

  4. Cliquez sur Configuration des tags, puis sélectionnez le tag Cloud Retail pour ouvrir le panneau de configuration des tags.

  5. Entrez votre clé d'API.

    Utilisez la clé que vous avez créée lors de la configuration de l'API Retail.

    Vos clés API sont disponibles sur la page API et services et services et identifiants de Google Cloud Console.

  6. Saisissez le numéro du projet Google Cloud dans lequel l'API Retail est activée.

    Le numéro de projet est disponible dans le tableau de bord Google Cloud Console.

  7. Pour le champ Source des données d'événement utilisateur :

    • Couche de données (recommandé): sélectionnez l'une des options suivantes:

      • L'e-commerce Google Analytics est implémenté via Tag Manager. Réutilisez la couche de données en tant que source de données d'événements au lieu d'en définir une nouvelle. Si nécessaire, elle utilise le schéma Google Analytics 4. Sinon, elle utilise l'e-commerce amélioré UA. Avec cette source de données, vous ne pouvez enregistrer que des événements add-to-cart, purchase-complete, detail-page-view et search. Les événements search sont enregistrés à l'aide des impressions d'e-commerce associées aux requêtes de recherche (voir Créer une variable de requête de recherche).

      • Vous utilisez l'e-commerce Google Analytics et vous pouvez insérer manuellement du code de couche de données. Reportez-vous au guide du développeur Tag Manager.

    • Variable - Cloud Retail : choisissez de renseigner une variable Tag Manager avec les champs obligatoires pour "Commerce de détail". Vous pouvez choisir cette option si vous n'utilisez pas l'e-commerce Google Analytics ou si vous n'avez pas les données nécessaires à la vente au détail. Si vous passez à cette source depuis l'ancienne option Couche de données - Cloud Retail, créez également une variable de couche de données avec la clé cloud_retail et associez-la à cette option Variable - Cloud Retail.

    • Variable - E-commerce : sélectionnez cette option si vous utilisez l'e-commerce Google Analytics dans votre couche de données et que vous ne pouvez pas renseigner manuellement le code de la couche de données.

      Dans le champ Lire les données d'e-commerce de la variable utilisateur qui s'affiche, choisissez une variable. Elle permet à l'API Retail de lire les données d'événement d'utilisateur d'e-commerce Google Analytics à partir d'une variable personnalisée que vous créez.

      La variable doit correspondre au format indiqué dans le guide du développeur GA4 ou dans le guide du développeur sur l'e-commerce amélioré. Pour créer une variable au format approprié, vous pouvez utiliser l'outil de création d'objets d'e-commerce amélioré, un modèle de variable personnalisée fourni dans la galerie de modèles de la communauté Tag Manager. Les modèles de la communauté ne sont pas gérés par Google. Pour utiliser ce modèle, consultez la documentation de la galerie de l'outil de création d'objets d'e-commerce amélioré afin de découvrir la documentation et d'autres ressources.

  8. Cliquez sur le bouton + Écraser une valeur du message UserEvent.

  9. Dans le champ Sélecteur de champ, sélectionnez visitorId comme champ, puis, dans Valeur du champ, sélectionnez la variable d'ID de visiteur que vous avez créée dans Créer une variable d'ID de visiteur.

  10. Cliquez sur Enregistrer.

    Votre tag Cloud Retail est créé.

Anciennes options pour la source de données

Auparavant, les options Source de données - E-commerce et Couche de données - Cloud Retail étaient disponibles. Ces anciennes options ne sont pas disponibles dans les nouvelles balises. Si vous remplacez une balise existante par une nouvelle source de données, prévisualisez-la avec Tag Manager pour vérifier le tag avant le déploiement. Lors de la transition:

  • Si vous avez utilisé Couche de données - E-commerce, vous pouvez passer à Couche de données. Le schéma Google Analytics 4 est utilisé, le cas échéant. Sinon, elle utilise l'e-commerce amélioré UA.

  • Si vous avez utilisé Couche de données - Cloud Retail, passez à l'option Variable - Cloud Retail. Créez une variable de couche de données avec une clé cloud_retail et associez-la à l'option Variable - Cloud Retail.

Suivant :

Créer une variable de requête de recherche

Si vous utilisez Retail Search, vous pouvez créer une variable dans Tag Manager pour les requêtes de recherche et l'associer à votre tag Cloud Retail. Cela permet à l'API Retail d'obtenir des requêtes de recherche à partir d'Analytics.

Les types de variables que vous créez dépendent de la source de données associée aux événements utilisateur.

  • Variable - E-commerce ou la couche de données avec le schéma d'e-commerce Google Analytics : créez une variable d'URL ou d'élément DOM dans Tag Manager, puis associez-la à votre balise Cloud Retail. En outre, activez l'option permettant à votre balise d'utiliser les impressions d'e-commerce Google Analytics pour créer des événements de recherche.
  • Variable - Cloud Retail ou couche de données renseignée manuellement : créez une variable d'URL ou d'élément DOM dans Tag Manager, puis associez-la à votre balise Cloud Retail. Pour que l'API Retail puisse déterminer si le type d'événement utilisateur est search, vous devez également :
    • Créer une variable de type constante pour les types d'événements recherchés et l'associer à votre tag.
    • Définissez le type d'événement de recherche dans votre couche de données ou votre variable Cloud Retail.

Créez et associez une variable d'URL ou d'élément DOM

Si vous utilisez Retail Search, vous pouvez créer une variable d'URL ou d'élément DOM qui contiendra les requêtes de recherche saisies sur votre site.

Au lieu de cette procédure, vous pouvez également configurer la couche de données qui fournit les informations sur la requête de recherche. Toutefois, vous pouvez choisir d'utiliser des variables Tag Manager si vous n'avez pas accès à la couche de données, ou si vous préférez ne pas configurer la couche de données.

Vous pouvez créer une variable de type URL ou une variable de type élément DOM. La méthode que vous créez et la configuration dépendent de la mise en œuvre de votre site :

  • Une variable d'URL récupère les requêtes de recherche à partir des URL de résultats de recherche de votre site. Utilisez cette variable si votre site inclut la chaîne de requête dans l'URL de ses résultats de recherche.
  • Une variable Élément DOM récupère les informations de requête de recherche à partir du DOM (Document Object Model) de votre site. Vous n'avez pas besoin de modifier le DOM pour utiliser cette variable. Toutefois, vous devez pouvoir lire et comprendre le DOM pour configurer correctement cette variable.

Commencez par créer une variable de type URL ou élément DOM :

  1. Dans Tag Manager, accédez à l'onglet Variables, puis cliquez sur Nouveau pour créer une variable définie par l'utilisateur.

  2. Donnez un nom à la variable en haut de la boîte de dialogue, tel que "search_variable".

  3. Saisissez les paramètres de la variable :

    Type "URL"

    1. Définissez Type de variable sur URL.

    2. Définissez le Type de composant sur Requête.

    3. Si vous spécifiez une clé de requête, définissez-la sur la clé précédant la requête de recherche dans votre URL.

      Par exemple, si l'URL est http://example.com/?q=shoes, la clé de requête est q. Dans cet exemple, la valeur de la variable serait définie sur shoes.

    Type "Élément DOM"

    1. Définissez le champ Type de variable sur Élément DOM.

    2. Définissez Méthode de sélection et saisissez l'ID d'élément ou le sélecteur d'éléments de la requête de recherche.

      Ce paramètre varie selon que votre site utilise un ID d'élément ou un sélecteur CSS pour identifier la requête de recherche.

    3. Si vous spécifiez un attribut, définissez-le sur l'attribut contenant le terme de requête de recherche.

      Par exemple, si la requête de recherche de votre DOM est <id="search" value="shoes">, l'attribut serait value. Dans cet exemple, la valeur de votre variable serait définie sur shoes.

  4. Cliquez sur Enregistrer pour enregistrer la variable.

Associez ensuite la variable à votre tag Cloud Retail :

  1. Dans Tag Manager, sur la page Tags, cliquez sur votre tag Cloud Retail pour le modifier.

  2. Si la source de données associée aux événements utilisateur de votre balise est Variable - E-commerce ou que vous utilisez la couche de données avec le schéma d'e-commerce Google Analytics, cochez la case Utiliser les impressions d'e-commerce amélioré pour créer des événements de recherche.

    Cela permet à l'API Retail de déterminer si le type d'un événement utilisateur est search sur la base des données de recherche obtenues à partir de ce tag.

  3. Dans la section Données d'événements utilisateur, cliquez sur le bouton + Écraser une valeur du message UserEvent.

  4. Sélectionnez searchQuery dans le sélecteur de champ, puis définissez la variable de requête de recherche en tant que valeur de champ.

  5. Enregistrez votre tag.

Suivant :

Créer et associer une variable constante

Vous pouvez suivre cette procédure si vous avez choisi Variable - Cloud Retail ou une couche de données renseignée manuellement en tant que source d'événement utilisateur pour votre tag Cloud Retail.

La création d'une variable de type constante pour les événements de recherche et la définition de cette variable en tant que remplacement d'événement utilisateur sur votre tag Cloud Retail permet à l'API Retail de déterminer si le type d'un événement utilisateur est search.

Au lieu de cette procédure, vous pouvez spécifier le type d'événement utilisateur search via la couche de données ou la variable Cloud Retail que vous utilisez comme source d'événement de tag. Sinon, procédez comme suit pour définir le type d'événement.

Commencez par créer une variable de type constante :

  1. Dans Tag Manager, accédez à l'onglet Variables, puis cliquez sur Nouveau pour créer une variable définie par l'utilisateur.

  2. Attribuez un nom à la variable en haut de la boîte de dialogue, tel que "search_constant".

  3. Définissez le Type de variable sur Constante.

  4. Saisissez search dans le champ Valeur.

  5. Cliquez sur Enregistrer pour enregistrer la variable.

Associez ensuite la variable à votre tag Cloud Retail :

  1. Sur la page Tag Manager, Tags, cliquez sur votre tag Cloud Retail pour le modifier.

  2. Dans la section Données d'événements utilisateur, cliquez sur le bouton + Écraser une valeur du message UserEvent.

  3. Sélectionnez eventType dans le sélecteur de champ, puis définissez la variable de requête de recherche en tant que valeur de champ.

  4. Enregistrez votre tag.

Ensuite, créez des déclencheurs d'événements pour votre tag.

Créer des déclencheurs d'événements pour votre balise Tag Manager

Créez des déclencheurs pour tous les types d'événements utilisateur que vos modèles Retail utiliseront.

Les tags Tag Manager doivent être associés à des déclencheurs qui contrôlent le moment où le tag doit être "exécuté" sur le site. Les déclencheurs écoutent les événements qui se produisent (par exemple, un utilisateur qui consulte la page d'accueil ou ajoute un article à son panier) et indiquent à votre tag d'envoyer les informations d'événement utilisateur à l'API Retail.

Tag Manager fournit des déclencheurs standards. Par exemple, Window Loader est un déclencheur pour les événements detail-page-view. Pour en savoir plus sur chaque type, consultez la section Types de déclencheurs dans la documentation de Tag Manager.

Vous définissez généralement le tag pour qu'il se déclenche lorsqu'un utilisateur affiche une page contenant les événements nécessaires à Retail (la page d'accueil, les pages d'informations détaillées sur les produits, les pages de panier ou la page de règlement). Dans ces cas, le tag doit se déclencher une fois la page chargée pour que les cookies soient disponibles et que toutes les variables de la couche de données soient renseignées. Pour ce faire, configurez vos déclencheurs pour qu'ils se déclenchent en cas d'événement Fenêtre chargée ou DOM prêt.

Vous devrez peut-être déclencher le tag lorsqu'une action est effectuée plutôt que lors du chargement de la page (par exemple, si l'ajout d'un article dans le panier ne force pas le rechargement d'une page). Dans ce cas, vous pouvez configurer cette action de clic sur votre site pour envoyer simultanément des mises à jour à la couche de données et associer le déclencheur à cette action.

Par exemple, si vous avez créé un déclencheur pour des événements add-to-cart, vous pouvez choisir le type de déclencheur pour Cliquer - Liens uniquement et configurer ce déclencheur pour qu'il se déclenche sur l'ID de clic (dans cet exemple, addtocart). Vous devez ensuite configurer le lien addtocart sur votre site pour mettre également à jour la couche de données avec de nouvelles valeurs lorsque l'utilisateur clique dessus :

  <a id="addtocart" href="javascript:void(0);"
         onclick="dataLayer.push({
                  'cloud_retail': {
                  'eventType': 'add-to-cart',
                  'visitorId': '456',
                  'cartId': 'mobile',
                  'productDetails': [{
                  'product': {
                  'id': '54321'
                  },
                  'quantity': 1
                  }]}});">Add to Cart</a>

Pour certains événements utilisateur, vous devez créer un déclencheur personnalisé. En règle générale, vous créez un déclencheur personnalisé dans Tag Manager en utilisant le nom de l'événement utilisateur. Si vous ne pouvez pas modifier votre code d'interface, vous pouvez créer un déclencheur personnalisé à l'aide de macros JavaScript. Pour en savoir plus sur les déclencheurs personnalisés, consultez la page Déclencheur d'événement personnalisé.

Procédez comme suit pour créer des déclencheurs dans Tag Manager :

Créer des déclencheurs pour votre balise Tag Manager

Si vous n'utilisez pas l'e-commerce Google Analytics, créez des déclencheurs d'événements pour tous les événements utilisateur dont vos modèles Retail ont besoin. Ensuite, associez vos nouveaux déclencheurs au tag Cloud Retail que vous avez créé dans Tag Manager.

Avant de commencer les étapes suivantes, assurez-vous d'avoir créé un tag Cloud Retail dans Tag Manager. Consultez l'article Créer une balise Tag Manager.

Commencez par créer les déclencheurs. Répétez cette procédure pour tous les événements utilisateur requis par vos modèles Retail :

  1. Sur la page Tag Manager, Déclencheurs, cliquez sur Nouveau > Configuration du déclencheur.

  2. Choisissez le type de déclencheur correspondant à l'événement utilisateur pour lequel vous créez un déclencheur.

  3. Enregistrez votre déclencheur.

Ensuite, associez vos nouveaux déclencheurs à votre tag Cloud Retail. Cette procédure est unique :

  1. Dans Tag Manager, sur la page Tags, cliquez sur votre tag Cloud Retail pour le modifier.

  2. Cliquez sur Déclenchement, sélectionnez vos nouveaux déclencheurs, puis cliquez sur Ajouter.

  3. Enregistrez votre tag.

Ensuite, prévisualisez votre tag et configurez la surveillance des erreurs d'enregistrement d'événements et des autres problèmes potentiels afin de vous assurer que l'API Retail continue de recevoir les données correctement.

Si vous utilisez la couche de données cloud_retail comme source d'événements utilisateur, veillez également à configurer votre couche de données.

Réutiliser les déclencheurs d'e-commerce Google Analytics

Si vous avez implémenté l'e-commerce Google Analytics via Tag Manager, les déclencheurs d'événements de réutilisation sont basés sur l'e-commerce Google Analytics pour le commerce.

Avec cette source de données, vous ne pouvez enregistrer que des événements add-to-cart, purchase-complete, detail-page-view et search. Les événements search sont enregistrés à l'aide des impressions d'e-commerce associées aux requêtes de recherche (voir Créer une variable de requête de recherche).

Le tableau suivant montre la correspondance entre les événements d'e-commerce et d'e-commerce amélioré de Google Analytics avec les événements de vente au détail.

Google Analytics 4 E-commerce amélioré Commerce
add_to_cart add add-to-cart
purchase purchase purchase-complete
view_item detail detail-page-view
view_item_list ou view_search_results impressions search (si combiné au champ searchQuery)

Avant de commencer, assurez-vous d'avoir :

  • Configurez une balise dans Tag Manager de type Google Analytics – Universal Analytics ou Google Analytics – Événement GA4, puis activez l'e-commerce amélioré ou GA4 sur celle-ci. Pour en savoir plus, consultez la documentation Tag Manager, le guide du développeur GA4 ou le guide du développeur pour l'e-commerce amélioré.
  • Configurez votre balise d'e-commerce amélioré ou GA4 dans Tag Manager pour qu'elle se déclenche lors des événements utilisateur que vous prévoyez d'enregistrer pour la vente au détail.
  • Vous avez créé une balise Cloud Retail dans Tag Manager, en utilisant la couche de données et la dimension "E-commerce" en tant que source de données d'événement utilisateur (voir Créer une balise Tag Manager).

Pour réutiliser les déclencheurs d'e-commerce Google Analytics:

  1. Sur la page Balises, Balises, cliquez sur votre balise d'e-commerce Google Analytics (type de balise Google Analytics - Universal Analytics ou Google Analytics - événement GA4) pour la modifier.

  2. Sous Paramètres avancés > Séquençage des balises, sélectionnez Déclencher une balise après <E-commerce amélioré ou nom de balise GA4> fires.

  3. Sélectionnez votre tag Cloud Retail en tant que Tag de nettoyage.

    Sélectionnez Don’t fire <Cloud Retail tag name> if <Enhanced Ecommerce or GA4 tag name> failed or is paused.

  4. Enregistrez votre tag.

Ensuite, prévisualisez votre tag et configurez la surveillance des erreurs d'enregistrement d'événements et des autres problèmes potentiels afin de vous assurer que l'API Retail continue de recevoir les données correctement.

Si vous utilisez la couche de données cloud_retail comme source d'événements utilisateur, veillez également à configurer votre couche de données.

Utiliser la couche de données cloud_retail avec Tag Manager

Si vous avez créé votre tag Cloud Retail dans Tag Manager pour utiliser la couche de données cloud_retail en tant que source d'événements utilisateur, configurez la variable dataLayer dans votre code HTML source, comme décrit dans la section Guide du développeur Tag Manager.

À propos de la couche de données

La plupart des tags Tag Manager nécessitent des données qui varient en fonction de l'utilisateur ou de la page (telles que des ID utilisateur ou des ID produit). Pour le tag Cloud Retail, ces données doivent être exposées de manière structurée via une couche de données afin que Tag Manager puisse les utiliser.

La couche de données est un objet JavaScript qui est généralement ajouté à une page dans le code côté serveur, ou à l'interface dans le code HTML ou en utilisant un modèle. Si une page est configurée avec la couche de données, elle contient du code semblable à celui-ci :

dataLayer = dataLayer || [];
dataLayer.push({
  'cloud_retail': {
    'eventType': 'home-page-view',
    'visitorId': 'visitor_a',

    'userInfo': {
      'userId': '789'
    },
  }
});

Ce code crée un objet dataLayer et lui attribue la structure cloud_retail en tant qu'élément de tableau.

Champs obligatoires dans la couche de données cloud_retail

L'onglet Événements utilisateur répertorie tous les champs requis et des exemples pour les types d'événements à transmettre à la couche de données cloud_retail.

Votre code ou vos modèles côté serveur doivent comporter les tags de script corrects sur chaque page à partir de laquelle vous souhaitez envoyer des événements. Une fois l'objet dataLayer renseigné correctement sur chaque page, vous devriez pouvoir tester le tag Cloud Retail.

Certains champs, tels que visitorId, sont obligatoires pour le message UserEvent, mais peuvent ne pas être disponibles lors du remplissage de la couche de données. Par exemple, visitorId peut être dérivé du cookie de l'utilisateur ou experimentIds du framework de tests A/B. Dans ce cas, utilisez une variable pour écraser le champ du tag Tag Manager.

Vous pouvez écraser les champs suivants :

  • visitorId
  • userInfo.userId
  • attributionToken
  • experimentIds

Pour savoir comment écraser un champ UserEvent dans Tag Manager, consultez la section Définir le champ visitorID dans Tag Manager, qui explique comment écraser la valeur du champ visitorId avec une variable définie par l'utilisateur.

L'exemple suivant montre la couche de données à inclure dans la page d'un UserEvent detail-page-view à l'aide de Tag Manager :

<script>
  dataLayer = dataLayer || [];
  dataLayer.push({
    'cloud_retail': {
      'eventType' : 'detail-page-view',
      'visitorId': 'visitor_a',
      'userInfo': {
          // The user and visitor ID fields can typically be
          // be populated from a client-side JavaScript
          // variable such as a cookie. If you set the user
          // and/or visitor ID values from the server,
          // populate the `userID`.
          'userId': 'user_a'
      },
      'attributionToken': 'attribution-token',
      // In most cases, the experiment ID field is populated from a
      // client side JavaScript variable as defined by the experiment
      // manager.
      // If you set the experiment ID value from the server,
      // populate the `experimentIds` field here.
      'productDetails': [
            {
              'product': {'id': '123'}
            }
      ],
    // You can use the 'cloud_retail' data layer element along with other
    // data layer elements.
    'ecommerce': {
      ...
    },
  }];
</script>

Prévisualiser votre balise Tag Manager

Le mode Aperçu de Tag Manager vous permet de tester les nouveaux tags avant de les publier sur votre site en production.

Pour en savoir plus sur le mode Aperçu, consultez la section consacrée au mode Aperçu dans la documentation de Tag Manager.

Pour vérifier que votre tag se déclenche correctement, procédez comme suit :

  1. Sur la page de présentation de Tag Manager, cliquez sur Aperçu.

    Le mode Aperçu de Tag Manager s'ouvre dans un nouvel onglet du navigateur.

  2. Saisissez les informations concernant votre site et cliquez sur Démarrer pour démarrer Tag Assistant.

    Tag Assistant démarre dans l'onglet de navigation actuel et votre site s'ouvre dans un nouvel onglet.

  3. Sur votre site, accédez à la page sur laquelle la balise Cloud Retail doit être déclenchée.

  4. Confirmez que Tag Assistant répertorie le tag Cloud Retail dans l'onglet Tags sous la section Tags déclenchés.

  5. Dans Tag Assistant, accédez à l'onglet Couche de données et vérifiez que les valeurs correctes de la couche de données cloud_retail ou d'e-commerce sont affichées.

Vérifier les erreurs dans la balise

Si certains champs sont incorrects ou manquants lors de l'aperçu du tag, le tag renvoie également une erreur, sauf s'il ne se déclenche pas du tout.

Vous pouvez consulter la page Monitoring &AMP; Analytics dans Google Cloud Console pour vérifier qu'elle ne comporte pas d'erreurs. Cette page enregistre la plupart des erreurs, à l'exception des erreurs de syntaxe, qui n'apparaissent généralement que dans les résultats de requête.

Vous pouvez suivre les étapes ci-dessous pour utiliser les outils de développement Chrome afin de rechercher les erreurs générées, y compris les erreurs de syntaxe.

  1. Activez le mode Aperçu dans Tag Manager pour votre site dans un navigateur Chrome, puis accédez à n'importe quelle page où le tag Cloud Retail doit être déclenché.

  2. Une fois le mode Aperçu ouvert, ouvrez les outils de développement et cliquez sur l'onglet Réseau.

  3. Actualisez la page.

  4. Dans les outils de développement, recherchez userEvent.

    L'onglet "Réseau" affiche l'événement userEvent:collect et son code d'état.

    • Une réponse 200 indique que votre tag est dans un bon état.
    • Les autres réponses, telles qu'une erreur 400 et la mise en surbrillance de l'événement en rouge, indiquent qu'un débogage est nécessaire.
  5. Double-cliquez sur le nom de l'événement pour exécuter la requête et afficher une réponse complète avec plus d'informations sur l'erreur.

    Par exemple, une erreur 400 contenant le message "visitorId est obligatoire et ne peut pas être vide" peut s'afficher indiquant que visitorId n'a pas été défini correctement.

  6. Si aucun userEvent n'est déclenché, consultez l'onglet Console des outils de développement et recherchez-y les erreurs de syntaxe dans la couche de données.

Surveiller l'état des importations

Il est important d'enregistrer les événements utilisateur pour obtenir des résultats de haute qualité. Vous devez surveiller les taux d'erreur d'enregistrement des événements et, les cas échéant, prendre des mesures adéquates. Pour en savoir plus, consultez la section Configurer des alertes pour les problèmes d'importation de données.

Étapes suivantes