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

Cette page décrit comment enregistrer des événements utilisateur en temps réel. Vertex AI Search pour le commerce utilise des événements utilisateur en temps réel pour générer des recommandations et des résultats de recherche. 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 à la fois aux recommandations et à la recherche. Une fois que vous avez enregistré des données, 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 À propos des é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 section À propos des é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. Consultez la section Importer un historique d'événements utilisateur.

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 de fournir des métriques de performances. L'inclusion d'un jeton d'attribution est obligatoire pour que Vertex AI Search pour le commerce fonctionne. Pour en savoir plus sur l'utilisation des jetons d'attribution, consultez la section Jetons d'attribution.

Les ID de visiteur sont obligatoires lorsque vous enregistrez des événements utilisateur. Pour en savoir plus sur les ID visiteur et les ID utilisateur, consultez la section À propos des informations utilisateur.

Enregistrer des événements utilisateur avec le taggage côté serveur

Le taggage côté serveur vous permet de déployer un seul conteneur côté serveur avec de nombreux clients en aval. Cela crée une seule source de vérité côté client, avec de nombreux consommateurs côté serveur. Cette architecture transfère la charge du Web vers le serveur, ce qui est intéressant pour les utilisateurs qui souhaitent maximiser les performances de leurs sites Web.

L'autre avantage du taggage côté serveur est qu'une seule balise côté serveur peut également prendre en charge de nombreux clients en amont, par exemple à la fois Web et mobile. Découvrez comment configurer le taggage côté serveur.

Vertex AI Search pour le commerce fournit sa propre balise côté serveur native.

La balise côté serveur Cloud Retail nécessite et accepte des paramètres similaires à ceux de la balise Web Cloud Retail, par exemple:

  • Numéro du projet
  • Clé API (pour l'authentification)
  • Forcements pour les champs clés tels que visitorId et searchQuery

La principale différence entre la version serveur et la version Web de la balise Cloud Retail est que vous ne pouvez pas définir la source de données. La source de données des balises de serveur est un flux de données envoyé par la balise Google dans le schéma GA4.

Configurer la balise Cloud Retail

É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 instructions détaillées sur cette tâche directement dans l'éditeur Cloud Shell, cliquez sur Visite guidée :

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.

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

Vertex AI Search pour le commerce 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 lors de l'importation de votre catalogue, rejoignez tous les événements enregistrés avant la fin de l'importation.

    Vous pouvez importer le catalogue 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 réassocier les événements qui ont été importés avant la fin de l'importation.

    Vertex AI Search for 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é 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 À propos des événements utilisateur.

  • Configurez des alertes Cloud Monitoring 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 Vertex AI Search for retail pour savoir comment corriger le problème.

  • Dans la mesure du possible, maintenez les données de vos é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 format d'identifiant unique sécurisé pour conserver l'anonymat des utilisateurs anonymes dans Vertex AI Search pour le commerce et protéger leur vie privée. 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).

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

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

Enregistrer des événements utilisateur à l'aide de 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 Analytics 4

Vous pouvez enregistrer des données d'événement utilisateur Google Analytics 4 dans Vertex AI Search pour le commerce.

Vérifier votre source de données

Assurez-vous que les données d'événement utilisateur que vous souhaitez importer sont correctement formatées.

Pour obtenir un tableau des champs Google Analytics 4 utilisés par Vertex AI Search pour le commerce et les champs Vertex AI Search pour le commerce auxquels ils sont mappés, consultez Champs d'événement utilisateur Google Analytics 4.

Pour connaître tous les paramètres d'événement Google Analytics, consultez la documentation de référence sur les événements Google Analytics.

Vérifiez les points suivants :

  1. Si vous importez des événements d'achat requis par certains modèles Vertex AI Search for retail, vos rapports sur les événements incluent des codes de devise. Consultez les paramètres d'événement purchase dans la documentation Google Analytics.

  2. Si vous envisagez d'importer des événements search, vos rapports sur les événements incluent les requêtes de recherche.

    L'importation d'événements search est acceptée, mais les événements search ne sont pas mappés à partir de Google Analytics 4 de la même manière que les autres types d'événements, car Google Analytics 4 n'est pas compatible de manière native avec le type d'événement search de la recherche Vertex AI pour le commerce. Lors de l'importation, les événements search sont créés à partir de Google Analytics 4 en combinant les informations des paramètres d'événement view_item_list et search_term.

    Consultez les paramètres d'événement search dans la documentation Google Analytics.

Enregistrer vos événements Google Analytics 4

Enregistrez un événement utilisateur en incluant les données JSON brutes encodées en URL de l'événement dans votre appel à la méthode userEvents.collect.

Pour le paramètre prebuilt_rule, utilisez la valeur ga4_bq.

Pour des raisons de lisibilité, l'exemple d'utilisation de l'appel userEvents.collect suivant définit d'abord GA4_EVENT comme variable contenant les données JSON brutes d'un exemple d'événement. L'appel userEvents.collect de l'exemple encode ensuite les données d'événement en URL à l'aide de la variable GA4_EVENT.

  1. Pour faciliter l'encodage de l'URL plus tard, vous pouvez définir GA4_EVENT comme variable contenant des données d'événement. Cet exemple montre un événement add-to-cart.

    GA4_EVENT='{
      "event_timestamp": 1622994083878241,
      "event_name": "add_to_cart",
      "user_pseudo_id": "352499268.1622993559",
      "items": [
        {
          "item_id": "11",
          "price": 29.99,
          "quantity": 3
        }
      ],
      "event_params": [
        {
          "key": "currency",
          "value": {
            "string_value": "CAD"
          }
        }
      ],
      "user_id": "Alice"
    }'
  2. Effectuez un appel userEvents.collect qui inclut les données JSON brutes encodées au format URL d'un événement utilisateur:

    curl \
    -G \
    --data-urlencode "raw_json=${GA4_EVENT}" \
    -i \
    "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:collect?key=EXAMPLEKEY1&prebuilt_rule=ga4_bq'"

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 à prendre pendant la configuration varient selon que vous utilisez Google Analytics et Google Analytics E-commerce. L'e-commerce Google Analytics peut être implémenté à l'aide de Google Analytics 4 ou de l'e-commerce amélioré. La balise Cloud Retail est compatible avec les deux.

Ni Google Analytics ni Google Analytics E-commerce ne sont obligatoires. Si vous ne les utilisez pas, vous pouvez configurer Variable – E-commerce lors de la création du tag Cloud Retail, ou renseigner manuellement le code de la couche de données de votre site après la création du tag.

L'e-commerce Google Analytics est une configuration supplémentaire pour Google Analytics qui transmet les titres, les ID, les prix, les détails des transactions et d'autres données d'e-commerce structurées à Google Analytics. Vertex AI Search for retail peut utiliser automatiquement la couche de données d'e-commerce Google Analytics. Si vous avez déjà configuré cette couche, la configuration peut être plus simple. Si vous n'avez pas configuré l'e-commerce Google Analytics pour Google Analytics, mais que vous souhaitez l'utiliser, consultez les instructions de configuration dans le guide du développeur GA4.

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

La valeur visitorId permet de 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 la variable.

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

    ID client

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

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

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

      Remplacez "G-XXXXXX" par votre ID de suivi Google Analytics. Pour trouver votre ID de suivi, consultez la section Qu'est-il arrivé à mon ID de suivi ?.

      function() {
       var tracker = ga.getByName('G-XXXXXX');
       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 à la recherche Vertex AI pour le 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 balise en haut du panneau (l'espace réservé est une variable sans titre), par exemple "Recherche Vertex AI pour le commerce".

  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 Vertex AI Search pour le commerce.

    Vos clés API sont disponibles sur la page API et services > Identifiants de la console Google Cloud.

  6. Saisissez le numéro du projet Google Cloud dans lequel Vertex AI Search for retail est activé.

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

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

    • Couche de données (recommandé): indiquez si votre implémentation sera l'une des suivantes:

      • Vous avez implémenté le suivi de l'e-commerce Google Analytics via Tag Manager. Réutilisez la couche de données en tant que source de données d'événements plutôt que de renseigner une autre source. Il utilise le schéma Google Analytics 4, le cas échéant. Sinon, l'e-commerce amélioré UA est utilisé. 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 d'impressions d'e-commerce combinées à des requêtes de recherche (voir Créer une variable de requête de recherche).

      • Vous utilisez l'e-commerce Google Analytics et vous pouvez renseigner manuellement le code de la couche de données. Consultez le guide du développeur Tag Manager.

    • Variable – Cloud Retail: sélectionnez cette option pour renseigner une variable Tag Manager avec les champs obligatoires pour Vertex AI Search pour le commerce. Vous pouvez choisir cette option si vous n'utilisez pas l'e-commerce Google Analytics ou si la quantité de données est insuffisante pour la recherche Vertex AI pour le commerce. Si vous passez à cette source à partir de 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: indiquez si vous n'utilisez pas l'e-commerce Google Analytics dans votre couche de données et que vous ne pouvez pas insérer 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. Cela permet à Vertex AI Search for retail de lire les données d'événement utilisateur de l'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. Pour créer une variable au format approprié, vous pouvez utiliser le générateur d'objets d'e-commerce amélioré, un modèle de variable personnalisée disponible Galerie de modèles de la communauté pour Tag Manager Les modèles de la communauté ne sont pas gérés par Google. Pour utiliser ce modèle, consultez la page de galerie du générateur d'objets d'e-commerce amélioré afin d'obtenir la documentation et d'autres ressources.

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

  9. sélectionnez visitorId comme champ pour Sélecteur de champ et sélectionnez la nouvelle variable d'ID visiteur créée dans Créer une variable d'ID visiteur pour Valeur du champ.

  10. Cliquez sur Enregistrer.

    Votre tag Cloud Retail est créé.

Anciennes options de sources de données

Auparavant, les options Couche de données - E-commerce et Couche de données - Cloud Retail étaient disponibles comme sources de données. Ces anciennes options ne sont pas disponibles dans les nouvelles balises. Si vous passez d'une balise existante à une nouvelle source de données, prévisualisez-la avec Tag Manager pour la vérifier avant de la déployer. Lorsque vous passez d'une édition à une autre:

  • 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, l'e-commerce amélioré UA est utilisé.

  • 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 la clé cloud_retail et associez-la à l'option Variable – Cloud Retail.

Suivant :

Créer une variable de requête de recherche

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

Les types de variables que vous créez dépendent de votre source de données d'événement utilisateur.

  • Variable – E-commerce ou la couche de données avec le schéma d'e-commerce Google Analytics : créez une variable d'élément URL ou DOM dans Tag Manager, puis associez-la à votre balise Cloud Retail. En outre, activez l'option permettant à votre tag d'utiliser les impressions d'e-commerce Google Analytics pour créer des événements de recherche.
  • Variable – Cloud Retail ou une couche de données renseignée manuellement : créez une variable d'élément URL ou DOM dans Tag Manager, puis associez-la à votre balise Cloud Retail. Pour déterminer si le type d'un événement utilisateur est search, vous devez également effectuer l'une des opérations suivantes :
    • 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 dans votre variable Cloud Retail.

Créer et associer une variable Tag Manager pour les requêtes de recherche

Si vous utilisez la recherche, vous pouvez créer une URL, un élément DOM ou une variable JavaScript personnalisée qui sera renseignée avec 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, une variable de type élément DOM ou une variable JavaScript (page) personnalisée. 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.
  • Une variable JavaScript personnalisée renvoie des données mises en forme par une fonction JavaScript. Cela est utile si vous avez des données existantes que vous souhaitez mettre en forme dans le schéma Cloud Retail ou Ecommerce.

Commencez par créer une variable Tag Manager de type URL, élément DOM ou JavaScript personnalisé:

  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.

    Type JavaScript personnalisé

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

    2. Remplacez les variables dans le code suivant, puis collez-le dans le volet JavaScript personnalisé.

    3. Dans le volet "JavaScript personnalisé", ajoutez du code JavaScript qui renvoie un événement de recherche dans le schéma Retail.

      L'exemple de code suivant transforme les données d'une variable Ecommerce Items existante en tableau productDetails utilisé par le schéma de recherche Vertex AI pour le commerce détail et renvoie un événement complet. Pour utiliser ce code, remplacez Ecommerce Items, Search Query et Search Filter par des variables dans votre implémentation Tag Manager.

      function () {
      
        var retail;
        var items = [];
      
        for (var i = 0; i < {{Ecommerce Items}}.length; i++) {
          var item = {'product':
                      {
                        'id': {{Ecommerce Items}}[i].item_id
                      }
                     };
      
          items.push(item);
        }
      
        retail = {
          'eventType': 'search',
          'searchQuery': '{{Search Query}}',
          'filter': '{{Search Filter}}',
          'productDetails': items
        }
      
        return retail;
      }
      
  4. 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. Si la source de données d'événement utilisateur de votre balise est Variable - E-commerce ou si vous utilisez la couche de données avec le schéma d'e-commerce Google Analytics, cochez la case Utiliser les impressions de la fonction d'e-commerce amélioré pour créer des événements de recherche.

    Cela permet à Vertex AI Search pour le commerce 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 utiliser cette procédure si vous avez choisi Variable – Cloud Retail ou une couche de données renseignée manuellement comme source d'événements utilisateur pour votre balise 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 à Vertex AI Search for 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 votre 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 tag Tag Manager

Créez des déclencheurs pour tous les types d'événements utilisateur que vos modèles Vertex AI Search for 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 balise d'envoyer les informations d'événement utilisateur à Vertex AI Search for 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 la balise pour qu'elle se déclenche lorsqu'un utilisateur affiche une page contenant les événements nécessaires à Vertex AI Search pour le commerce (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 tag 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 Vertex AI Search for 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 la section Créer un tag 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 Vertex AI Search pour le commerce:

  1. Sur la page Déclencheurs de Tag Manager, 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 balise et configurez la surveillance des erreurs d'enregistrement d'événements et des autres problèmes potentiels afin de vous assurer que les données continuent d'être reçues 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 mis en œuvre l'e-commerce Google Analytics via Tag Manager, réutilisez les déclencheurs d'événement de votre e-commerce Google Analytics pour la recherche Vertex AI pour le retail.

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 d'impressions d'e-commerce combinées à des requêtes de recherche (voir Créer une variable de requête de recherche).

Le tableau suivant montre comment les événements d'e-commerce et d'e-commerce avancé de Google Analytics correspondent aux événements Vertex AI Search pour le commerce.

Google Analytics 4 E-commerce amélioré Vertex AI Search pour le 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é avec le champ searchQuery)

Avant de commencer, assurez-vous d'avoir :

  • Configuré un tag dans Tag Manager de type Google Analytics – Événement GA4 et activé l'e-commerce amélioré ou GA4 dessus. Pour en savoir plus, consultez la documentation Tag Manager et le guide du développeur GA4.
  • Configuré votre tag d'e-commerce amélioré ou GA4 dans Tag Manager pour qu'il se déclenche en fonction des événements utilisateur que vous prévoyez d'enregistrer pour Vertex AI Search pour le commerce.
  • Vous avez créé un tag Cloud Retail dans Tag Manager, avec "Couche de données" ou "Variable – E-commerce" comme source de données d'événements utilisateur (consultez la page Créer un tag Tag Manager).

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

  1. Sur la page Tags de Tag Manager, cliquez sur votre balise d'e-commerce Google Analytics (type Google Analytics – Événement GA4) pour la modifier.

  2. Sous Paramètres avancés > Séquençage des balises, sélectionnez Déclencher un tag après <Nom du tag d'e-commerce amélioré ou GA4>.

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

    Sélectionnez Ne pas déclencher <Nom du tag Cloud Retail > si<Nom du tag d'e-commerce amélioré ou GA4> échoue ou est suspendu.

  4. Enregistrez votre tag.

Ensuite, prévisualisez votre balise et configurez la surveillance des erreurs d'enregistrement d'événements et des autres problèmes potentiels afin de vous assurer que les données continuent d'être reçues 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

À propos des é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 par 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.

Rechercher les erreurs de 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 accéder à la page Surveillance dans la console Search for Retail pour y rechercher des 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 pour les développeurs 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.

Afficher les événements enregistrés

Consultez les métriques d'intégration des événements dans l'onglet Événements de la page Données de la console Search for Retail. Cette page présente tous les événements écrits ou importés au cours de l'année précédente. Les métriques peuvent mettre jusqu'à 24 heures à s'afficher après l'ingestion des données.

Accéder à la page "Données"

Étape suivante