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 de cette page s'appliquent à la fois aux recommandations et à la recherche. Une fois les données enregistré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.

Pour en savoir plus sur les événements utilisateur, y compris sur les types d'événements utilisateur et obtenir des exemples de code JSON pour tous les types, consultez À 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 À 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 Importer l'historique des événements utilisateur.

Si l'événement utilisateur que vous enregistrez est la première fois qu'un utilisateur interagit avec un produit en fonction d'une recommandation ou de résultats de recherche fournis précédemment, un jeton d'attribution active les 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.

Veuillez indiquer des ID de visiteur lors de l'enregistrement des événements utilisateur. Pour en savoir plus sur les ID de visiteur et les ID utilisateur, consultez la section À 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 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 a besoin de 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 en même temps que vous enregistrez 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 pour le commerce tente de joindre des événements utilisateur enregistrés avec les 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 qui ne figure 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 rejoindre les événements enregistrés lors de l'importation. Il est normal d'avoir quelques événements non associés. Toutefois, si le pourcentage d'événements non associés atteint au moins 5% du nombre total d'événements utilisateur, assurez-vous que votre catalogue est à jour, réassociez les événements enregistrés avant la mise à jour complète du catalogue et cherchez pourquoi ils sont créé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 afin de savoir si vos 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 conseiller Vertex AI Search pour le commerce afin de savoir comment résoudre 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 identifiant unique sécurisé pour préserver l'anonymat des utilisateurs dans Vertex AI Search pour le commerce, et pour protéger leur confidentialité. Vous êtes responsable du masquage des informations personnelles (PII) telles que les adresses e-mail ou personnelles dans vos données.

Enregistrer les é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 Analytics 4

Vous pouvez enregistrer les données d'événements 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 mises en forme.

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

Pour 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 pour le commerce, 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 prévoyez d'importer des événements search, les rapports sur les événements incluent les requêtes de recherche.

    Vous pouvez importer des événements search, 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 Vertex AI Search search 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 au format URL pour 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 suivant d'utilisation de l'appel userEvents.collect définit d'abord GA4_EVENT comme variable contenant les données JSON brutes pour un exemple d'événement. L'appel userEvents.collect dans l'exemple encode ensuite les données d'événement en URL à l'aide de la variable GA4_EVENT.

  1. Pour faciliter l'encodage des URL par la suite, vous pouvez définir GA4_EVENT en tant que variable contenant des données d'événement. Cet exemple présente 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 que vous prenez lors de la configuration varient selon que vous utilisez ou non Google Analytics ou l'e-commerce Google Analytics. Vous pouvez implémenter l'e-commerce Google Analytics à l'aide de Google Analytics 4 ou de l'e-commerce amélioré. Le tag Cloud Retail est compatible avec les deux.

Ni Google Analytics, ni l'e-commerce Google Analytics ne sont obligatoires. Si vous ne les utilisez pas, vous pouvez configurer la Variable – E-commerce lors de la création de la balise Cloud Retail, ou renseigner 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 les titres de produits, les ID, les prix, les détails des transactions et d'autres données d'e-commerce structurées à Google Analytics. Vertex AI Search pour le commerce peut utiliser automatiquement la couche de données Google Analytics "E-commerce". Si vous l'avez déjà configurée, la configuration peut être plus simple. Si l'e-commerce Google Analytics n'est pas configuré pour Google Analytics, mais que vous souhaitez l'utiliser, consultez les informations détaillées et les instructions de configuration dans le guide du développeur GA4 ou le guide du développeur pour 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

La valeur visitorId sert à suivre les utilisateurs. visitorId est généralement un ID de session et est obligatoire 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 le définir comme source des ID de visiteur. Utilisez toujours une source d'ID de visiteur cohérente lors de l'ingestion d'événements utilisateur historiques et en temps réel.

    ID client

    Dans BigQuery Google Analytics 360, cette variable correspond au champ clientID du schéma d'exportation BigQuery d'Universal Analytics. Dans Google Analytics 4, cette variable correspond au champ user_pseudo_id du schéma d'exportation BigQuery de 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 une balise dans Tag Manager pour envoyer des informations sur les événements utilisateur à Vertex AI Search pour le commerce.

  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 Variable sans titre), par exemple "Vertex AI Search 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 lorsque vous avez configuré 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 pour le commerce 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 respecte l'une des conditions suivantes:

      • Vous avez intégré le commerce électronique Google Analytics via Tag Manager. Réutilisez la couche de données comme source de données d'événements au lieu d'en remplir une nouvelle. Le schéma Google Analytics 4 est utilisé, le cas échéant. Sinon, il utilise l'e-commerce amélioré UA. Avec cette source de données, vous ne pouvez enregistrer que les é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 pouvez insérer 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 l'e-commerce Google Analytics ne dispose pas des données nécessaires à Vertex AI Search pour le commerce. Si vous passez à cette source depuis l'ancienne option de 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 si 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. Cela permet à Vertex AI Search pour le commerce de lire les données d'événement utilisateur Google Analytics E-commerce à 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 pour l'e-commerce amélioré. Pour créer une variable au bon format, vous pouvez utiliser l'outil de création d'objets d'e-commerce amélioré, un modèle de variable personnalisée issu de 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 page de la galerie de l'outil de création d'objets d'e-commerce amélioré afin d'obtenir de la documentation et d'autres ressources.

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

  9. Dans Sélecteur de champ, sélectionnez visitorId comme champ, et sous Valeur du champ, sélectionnez la nouvelle 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éé.

Options des anciennes sources de données

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

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

  • Si vous avez utilisé la 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. Vertex AI Search pour le commerce peut ainsi obtenir des requêtes de recherche depuis 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 URL ou une variable d'élément DOM dans Tag Manager et 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 et associez-la à votre balise Cloud Retail. Pour déterminer si un événement utilisateur est de type 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 la 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é 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 d'élément DOM ou une variable JavaScript (page) personnalisée. Le type de site que vous créez et la manière dont vous le configurez dépendent de l'implémentation 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é renvoie des données mises en forme par une fonction JavaScript. Cela est utile si vous souhaitez mettre en forme des données existantes dans le schéma Cloud Retail ou d'e-commerce.

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-les 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 dans le tableau productDetails utilisé par le schéma Vertex AI Search pour le commerce, 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. Dans Tag Manager, sur la page Tags, cliquez sur votre tag Cloud Retail pour le modifier.

  2. Si la source de données d'événements 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 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 en fonction 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 comme source d'événements utilisateur pour votre tag Cloud Retail.

Créer une variable de type constant pour les événements de recherche et la définir en tant que remplacement d'événement utilisateur sur votre tag Cloud Retail permet à Vertex AI Search pour le commerce 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 balise. 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 Vertex AI Search pour le commerce 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, lorsqu'un utilisateur consulte la page d'accueil ou ajoute un article à son panier) et invite votre balise à envoyer ces informations d'événement utilisateur à Vertex AI Search pour le commerce.

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 consulte une page contenant les événements nécessaires à Vertex AI Search pour le commerce (comme la page d'accueil, les pages d'informations détaillées sur les produits, les pages du panier ou la page de paiement terminé). 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 Vertex AI Search 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 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 les 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, puis configurez la surveillance des erreurs d'enregistrement des événements et d'autres problèmes pour vous assurer que les données continuent à être reçues.

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, réutilisez les déclencheurs d'événements de votre compte d'e-commerce Google Analytics pour Vertex AI Search pour le commerce.

Avec cette source de données, vous ne pouvez enregistrer que les é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 comment les événements d'e-commerce Google Analytics et d'e-commerce amélioré sont mappés avec Vertex AI Search pour les événements de vente au détail.

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 (s'il est associé au champ searchQuery)

Avant de commencer, assurez-vous d'avoir :

  • Configurez une balise de type Google Analytics - Universal Analytics ou Google Analytics - Événement GA4 dans Tag Manager, et activez l'e-commerce amélioré ou GA4. Pour en savoir plus, consultez la documentation Tag Manager, ainsi que le guide du développeur GA4 ou le guide du développeur pour l'e-commerce amélioré.
  • configuré votre balise d'e-commerce amélioré ou GA4 dans Tag Manager pour qu'elle se déclenche sur les événements utilisateur que vous prévoyez d'enregistrer pour Vertex AI Search pour le commerce ;
  • Création d'une balise Cloud Retail dans Tag Manager, avec "Couche de données" ou "Variable - E-commerce" comme 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 de Tag Manager, 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 le déclenchement de <E-commerce amélioré ou nom de la balise GA4>.

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

    Sélectionnez Ne pas déclencher <nom de la balise Cloud Retail > en cas d'échec ou de mise en veille de la balise <E-commerce amélioré ou nom de la balise GA4>.

  4. Enregistrez votre tag.

Ensuite, prévisualisez votre balise, puis configurez la surveillance des erreurs d'enregistrement des événements et d'autres problèmes pour vous assurer que les données continuent à être reçues.

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

La page À propos des événements utilisateur liste tous les champs obligatoires 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.

Rechercher les erreurs de tags

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 les erreurs sur la page Surveillance de la console de recherche Retail. Cette page consigne la plupart des erreurs, à l'exception des erreurs de syntaxe, qui n'apparaissent généralement que dans les résultats de la 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.

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 source d'informations unique côté client, avec de nombreux consommateurs côté serveur. Cette architecture transfère la charge du Web vers le serveur, ce qui la rend souhaitable pour les utilisateurs qui souhaitent maximiser les performances de leurs sites Web.

L'autre avantage du taggage côté serveur est qu'un seul tag côté serveur peut également être compatible avec de nombreux clients en amont, par exemple Web et mobile. Découvrez comment configurer le taggage côté serveur.

Vertex AI Search pour le commerce fournit son propre tag natif côté serveur.

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

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

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

Configurer la balise Cloud Retail

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

Affichez 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 passée. Une fois l'ingestion de données réussie, l'affichage des métriques dans la console peut prendre jusqu'à une heure.

Accéder à la page "Données"

Étapes suivantes