"Retail" devient Vertex AI Search pour le commerce. Nous sommes en train de mettre à jour le contenu pour refléter le nouveau branding.

Cette page a été traduite par l'API Cloud Translation.

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 les é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 les recommandations et la recherche. Après l'enregistrement données, les deux services peuvent utiliser ces événements. Vous n'avez donc pas besoin d'importer deux fois les mêmes données si vous utilisez les deux services.

Pour en savoir plus sur les événements utilisateur, y compris les types d'événements utilisateur et un exemple de code JSON pour tous les types, consultez À propos des événements utilisateur.

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

À l'aide d'un pixel JavaScript.
En envoyant des événements directement à l'API depuis votre serveur backend.
À l'aide d'un tag Tag Manager.

Vous trouverez ci-dessous des exemples d'enregistrement d'événement utilisateur de type detail-page-view. Autre d'événements utilisateur, 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 les événements utilisateur historiques.

Si l'événement utilisateur que vous enregistrez correspond à la première interaction d'un utilisateur un produit sur la base d'une recommandation ou de résultats de recherche précédemment fournis ; inclure un jeton d'attribution permet 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.

Les ID de visiteur sont obligatoires 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 résultats. 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 : les événements de jointure qui ont été importés avant la fin de l'importation.

Vertex AI Search pour le commerce tente de joindre les événements utilisateur enregistrés avec des 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 l'entraînement vos modèles. C'est ce qu'on appelle un « non associé » . Si vous avez enregistré des événements avant votre catalogue a été entièrement importé, vous devez rejoindre des événements enregistrés lors de l'importation. Avoir quelques des événements non associés est attendu. 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 la date, les événements de réassociation enregistrés avant la mise à jour complète du catalogue, et déterminer pourquoi les événements non associés 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 pour savoir si votre les processus d'enregistrement des événements utilisateur subissent des pannes.
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 2 Go ou inférieure. Toi peut inclure au maximum 100 en une seule 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 pour le commerce concernant la façon de 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 une forme sécurisée d'identifiant unique pour que les utilisateurs restent anonymes sur Vertex AI Search pour le commerce et à protéger les données confidentialité. Vous êtes responsable du masquage des informations personnelles (PII) telles que les adresses e-mail ou personnelles dans vos données.

Enregistrer des événements utilisateur avec un pixel JavaScript

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

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

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

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

</script>

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

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

Voici un exemple abrégé qui explique le format de l'ID client dans un événement utilisateur. Remplacer "G-XXXXXX" avec 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 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 les é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énements utilisateur que vous souhaitez importer sont correctement formatées.

Pour une table des champs Google Analytics 4 que Vertex AI Search pour le commerce et à quels champs Vertex AI Search pour le commerce sont mappés, consultez Champs d'événement utilisateur dans 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 :

Si vous importez des événements d'achat, auxquels certains utilisateurs 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.
Si vous prévoyez d'importer search événements, vos rapports sur les événements incluent la recherche requêtes.

Vous pouvez importer des événements search, mais les événements search ne sont pas mappés depuis Google Analytics 4, tout comme les autres types d'événements car Google Analytics 4 n'est pas compatible de façon native Type d'événement Vertex AI Search pour le commerce search. Pendant l'importation, search événements sont construits à partir de Google Analytics 4 en combinant les informations à partir 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 pour l'événement dans votre à 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. . L'appel userEvents.collect dans l'exemple encode ensuite l'événement en URL à l'aide de la variable GA4_EVENT.

Pour faciliter l'encodage des URL par la suite, vous pourrez définir GA4_EVENT comme variable contenant des données d'événement. Cet exemple illustre 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"
}'

Effectuer un appel userEvents.collect qui inclut les données JSON brutes encodées en 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 les é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 Google Analytics et l'e-commerce Google Analytics. L'e-commerce Google Analytics être implémentés à l'aide de Google Analytics 4 ou de l'e-commerce amélioré. Le tag Cloud Retail les accepte dans les deux cas.

Ni Google Analytics, ni le suivi de l'e-commerce Google Analytics ne sont requis. si vous si vous ne les utilisez pas, vous pouvez configurer Variable - E-commerce lorsque vous créez la balise Cloud Retail, ou saisissez manuellement le code de la couche de données de votre site lors de la création du tag.

L'e-commerce Google Analytics est une configuration supplémentaire Google Analytics qui transmet les titres, identifiants, prix, transactions des détails et d'autres données d'e-commerce structurées vers Google Analytics. Vertex AI Search pour le commerce peut utiliser automatiquement la solution d'e-commerce Google Analytics couche de données. Ainsi, si vous l'avez déjà fait, la configuration peut être plus simple. Si pour lesquelles l'e-commerce Google Analytics n'est pas configuré Google Analytics, mais que vous souhaitez l'utiliser, voir plus de détails et de configuration les instructions 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 permet d'effectuer le suivi des 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 :

Dans Tag Manager, accédez à l'onglet Variables, puis cliquez sur Nouveau pour créer une variable définie par l'utilisateur.
Attribuez un nom à la variable en haut de la boîte de dialogue, tel que "GA visitorId".
Saisissez les paramètres de votre variable.

Vous pouvez utiliser l'ID client ou l'ID de cookie pour définir la source du visiteur. ID. Utilisez toujours une source cohérente d'ID de visiteur lors de l'ingestion de données historiques des événements utilisateur en temps réel.
ID client
Dans Google Analytics 360 BigQuery, correspond au champ clientID dans Schéma d'exportation BigQuery dans Universal Analytics Dans Google Analytics 4, cette variable correspond à Champ user_pseudo_id dans Schéma de BigQuery Export pour Google Analytics 4
1. Définissez Type de variable sur JavaScript personnalisé.
2. Saisissez le script suivant dans le champ JavaScript personnalisé.
  
  Remplacer "G-XXXXXX" avec 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('G-XXXXXX');
 return tracker.get('clientID');
}
```
3. Cliquez sur Enregistrer pour enregistrer la variable.
ID du cookie
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 les informations liées aux événements utilisateur Vertex AI Search pour le commerce.

Connectez-vous à Tag Manager. et sélectionnez le conteneur de votre site.
Accédez à l'onglet Tags et cliquez sur Nouveau pour ajouter un tag.
Attribuez un nom à votre tag en haut du panneau (l'espace réservé est Variable sans titre), telle que "Vertex AI Search pour le commerce".
Cliquez sur Configuration des tags, puis sélectionnez le tag Cloud Retail pour ouvrir le panneau de configuration des tags.
Entrez votre clé d'API.

Utilisez la clé que vous avez créée lors de la configuration de Vertex AI Search pour le commerce.

Vous pouvez accéder à vos clés API dans la section API et Services > Identifiants de la console Google Cloud.
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 votre console Google Cloud.
Pour le champ Source des données d'événement utilisateur :
- Couche de données (recommandé): indiquez si vous souhaitez intégrer l'une des les éléments suivants:
  - Vous avez implémenté l'e-commerce Google Analytics via Tag Manager. Réutiliser la couche de données comme source de données pour les événements au lieu d'en remplir un nouveau. Cette fonctionnalité utilise l'API Google Analytics 4 schémas, le cas échéant. Sinon, il utilise l'e-commerce amélioré UA. Avec cette source de données, vous ne pouvez enregistrer que add-to-cart, purchase-complete, detail-page-view et search. search événements sont enregistrés avec des impressions du commerce électronique associées aux requêtes de recherche (voir Créer une variable de requête de recherche).
  - Vous utilisez l'e-commerce Google Analytics et vous pouvez renseigner manuellement les données du code de couche. Consultez le Guide du développeur Tag Manager
- Variable - Cloud Retail: sélectionnez cette option pour renseigner un tag Tag Manager. avec les champs obligatoires pour Vertex AI Search pour le commerce. Vous pourriez sélectionnez cette option si vous n'utilisez pas l'e-commerce Google Analytics ou L'e-commerce Google Analytics ne dispose pas des données nécessaires pour Vertex AI Search pour le commerce. Si vous passez de l'ancienne couche de données à cette source : Cloud Retail, créez également une variable de couche de données avec une clé cloud_retail et l'associer à cette Variable - Cloud Retail .
- Variable - E-commerce: sélectionnez cette option si vous n'utilisez pas cette colonne l'e-commerce Google Analytics dans votre couche de données, mais vous ne pouvez pas pour insérer 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. Vertex AI Search pour le commerce peut ainsi lire Données d'événement utilisateur d'e-commerce Google Analytics provenant d'une variable personnalisée que vous créez.
  
  La variable doit correspondre au format indiqué dans la Guide du développeur GA4 ou la Guide du développeur pour l'e-commerce amélioré Pour construire une variable au bon format, vous pouvez utiliser Outil de création d'objets d'e-commerce amélioré un modèle de variable personnalisée issu de 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, Consulter la galerie de la galerie de l'outil de création d'objets d'e-commerce amélioré pour obtenir de la documentation et d'autres ressources.
Cliquez sur le bouton + Écraser une valeur du message UserEvent.
Pour Sélecteur de champ, sélectionnez visitorId comme champ. Valeur du champ : sélectionnez la nouvelle variable d'ID de visiteur que vous avez créée dans Créez une variable d'ID de visiteur.
Cliquez sur Enregistrer.

Votre tag Cloud Retail est créé.

Options des anciennes sources de données

Auparavant, les métriques 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 . Si vous remplacez une balise existante par une nouvelle source de données, prévisualisez-la avec Tag Manager pour la valider avant le déploiement. Lorsque vous passez au Pixel:

Si vous avez utilisé la 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, 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éer une variable de couche de données avec une clé cloud_retail et l'associer à l'option Variable - Cloud Retail.

Si vous utilisez la recherche, créez une variable pour les requêtes de recherche et associez-la à votre nouvelle .
Créez des déclencheurs d'événements pour votre tag.

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 associez-le à votre tag Cloud Retail. Vertex AI Search pour le commerce peut ainsi récupérer des requêtes de recherche Analytics.

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

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

Cré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 un élément qui sera renseignée avec les requêtes de recherche saisies dans votre 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 d'URL, une variable de type d'élément DOM ou une variable personnalisée JavaScript (page). Celui que vous créez et comment vous le configurez, dépend 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 formatées par un . Cela est utile si vous souhaitez formater des données existantes le schéma Cloud Retail ou e-commerce.

Commencez par créer une variable Tag Manager de type "URL", "Élément DOM" ou "Personnalisée". JavaScript:

Dans Tag Manager, accédez à l'onglet Variables, puis cliquez sur Nouveau pour créer une variable définie par l'utilisateur.
Donnez un nom à la variable en haut de la boîte de dialogue, tel que "search_variable".
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 et collez-le dans le Volet JavaScript personnalisé.
3. Dans le volet "JavaScript personnalisé", ajoutez du code JavaScript qui renvoie une 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 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 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;
}
```
Cliquez sur Enregistrer pour enregistrer la variable.

Associez ensuite la variable à votre tag Cloud Retail :

Sur la page Tag Manager, Tags, cliquez sur votre tag Cloud Retail pour le modifier.
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 Créer des événements de recherche à l'aide des impressions d'e-commerce amélioré

Vertex AI Search pour le commerce peut ainsi déterminer si le type d'un événement utilisateur search selon les données de recherche qu'elle obtient à partir de cette balise.
Dans la section Données d'événements utilisateur, cliquez sur le bouton + Écraser une valeur du message UserEvent.
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.
Enregistrez votre tag.

Si vous avez choisi d'utiliser une variable Cloud Retail ou des données renseignées manuellement comme source d'événement utilisateur pour votre balise Cloud Retail, consultez Créez et associez une variable constante.
Créez des déclencheurs d'événements pour votre tag.

Créer et associer une variable constante

Vous pouvez suivre cette procédure si vous avez choisi Variable - Cloud Retail ou couche de données renseignée manuellement comme source d'événements utilisateur pour votre environnement Cloud Retail .

Créer une variable de type constante pour les événements de recherche et la définir en tant qu'utilisateur sur votre tag Cloud Retail permet à Vertex AI Search pour le commerce Déterminer si le type d'un événement utilisateur est search

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

Commencez par créer une variable de type constante :

Dans Tag Manager, accédez à l'onglet Variables, puis cliquez sur Nouveau pour créer une variable définie par l'utilisateur.
Attribuez un nom à la variable en haut de la boîte de dialogue, tel que "search_constant".
Définissez le Type de variable sur Constante.
Saisissez search dans le champ Valeur.
Cliquez sur Enregistrer pour enregistrer la variable.

Associez ensuite la variable à votre tag Cloud Retail :

Sur la page Tag Manager, Tags, cliquez sur votre tag Cloud Retail pour le modifier.
Dans la section Données d'événements utilisateur, cliquez sur le bouton + Écraser une valeur du message UserEvent.
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.
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éer des déclencheurs pour tous les types d'événements utilisateur dans vos modèles Vertex AI Search pour le commerce utilisera.

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 la page d'accueil ou l'ajout d'un article à leur panier) et invite votre balise à d'envoyer ces informations d'événements 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.

Généralement, vous définissez la balise pour qu'elle se déclenche lorsqu'un utilisateur consulte une page présentant le paramètre les événements nécessaires à Vertex AI Search pour le commerce (par exemple, la page d'accueil, les informations détaillées sur le produit, pages, pages du panier ou pages 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 :

Si aucun déclencheur existant n'est configuré : Créez des déclencheurs pour votre tag Tag Manager
Si vous avez déjà configuré des déclencheurs d'e-commerce Google Analytics: vous pouvez réutiliser les déclencheurs que vous avez configurés pour l'e-commerce Google Analytics au lieu de en créer de nouveaux. Voir Réutiliser des déclencheurs d'e-commerce Google Analytics

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 dont vos modèles Vertex AI Search pour le commerce 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 Les modèles Vertex AI Search pour le commerce nécessitent les éléments suivants:

Sur la page Déclencheurs de Tag Manager, cliquez sur Nouveau > Configuration du déclencheur.
Choisissez le type de déclencheur correspondant à l'événement utilisateur pour lequel vous créez un déclencheur.
Enregistrez votre déclencheur.

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

Dans Tag Manager, sur la page Tags, cliquez sur votre tag Cloud Retail pour le modifier.
Cliquez sur Déclenchement, sélectionnez vos nouveaux déclencheurs, puis cliquez sur Ajouter.
Enregistrez votre tag.

Ensuite, prévisualisez votre balise. configurer la surveillance des erreurs d'enregistrement des événements et d'autres problèmes pour s’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 des 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 issus 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 add-to-cart, purchase-complete, detail-page-view et search. search événements sont enregistrés avec des impressions du commerce électronique associées aux requêtes de recherche (voir Créer une variable de requête de recherche).

Le tableau suivant montre comment les rapports Les événements d'e-commerce amélioré sont mappés 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` (en cas de combinaison avec le champ `searchQuery`)

Avant de commencer, assurez-vous d'avoir :

Configurez une balise de type Google Analytics – Universal dans Tag Manager. Analytics ou Google Analytics – Événement GA4, et activé l'e-commerce amélioré ou GA4. Voir la documentation Tag Manager et Guide du développeur GA4 ou la Guide du développeur pour l'e-commerce amélioré pour en savoir plus.
configuré votre balise d'e-commerce amélioré ou GA4 dans Tag Manager ; déclencher les événements utilisateur que vous prévoyez d'enregistrer pour Vertex AI Search pour le commerce.
Création d'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 (voir Créez une balise Tag Manager.

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

Le Tag Manager, Balises, cliquez sur votre balise d'e-commerce Google Analytics (type de balise Google Analytics - Universal Analytics ou Google Analytics - Événement GA4) pour le modifier.
Sous Paramètres avancés > Séquençage des balises, sélectionnez Déclencher une balise après <Nom de la balise GA4 ou de l'e-commerce amélioré> incendies.
Sélectionnez votre tag Cloud Retail en tant que Tag de nettoyage.

Sélectionnez Ne pas déclencher <nom de la balise Cloud Retail>. if <Nom de la balise GA4 ou e-commerce amélioré> échoue ou est en pause.
Enregistrez votre tag.

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 : liste tous les champs obligatoires et des exemples pour 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 :

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.
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.
Sur votre site, accédez à la page sur laquelle la balise Cloud Retail doit être déclenchée.
Confirmez que Tag Assistant répertorie le tag Cloud Retail dans l'onglet Tags sous la section Tags déclenchés.
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 consulter la page Surveillance dans le Recherchez les erreurs éventuelles dans la console Retail. Cette page consigne la plupart des erreurs, à l'exception pour les erreurs de syntaxe, qui n'apparaissent généralement que dans les résultats de requêtes.

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.

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é.
Une fois le mode Aperçu ouvert, ouvrez les outils de développement et cliquez sur l'onglet Réseau.
Actualisez la page.
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.
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.
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 conteneur unique côté serveur avec de nombreux clients en aval. Cela crée une source unique de vérité sur le client avec de nombreux clients côté serveur. Cette architecture libère la charge sur le Web et dans le serveur, ce qui convient aux utilisateurs qui souhaitent optimiser les performances de leurs sites Web.

L'autre avantage du taggage côté serveur est qu'un seul tag côté serveur peut sont également compatibles 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 Cloud Retail côté serveur nécessite et accepte des paramètres semblables à ceux le tag Web Cloud Retail, par exemple:

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

La principale différence entre la version serveur et la version Web du cloud vous ne pouvez pas définir la source de données. La source de données pour les tags serveur sont un flux de données envoyé depuis 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

Afficher les métriques d'intégration d'événements dans l'onglet Événements de la console Search for Retail Données. Cette page affiche tous les événements écrits ou importés au cours de l'année passée. Les métriques peuvent occuper à une heure pour apparaître dans la console après une ingestion de données réussie.

Accéder à la page "Données"

Étape suivante

En savoir plus sur les événements utilisateur.
Associez des événements s'ils ont été enregistrés avant la fin de l'importation du catalogue.
Apprendre à importer et gérer des événements utilisateur.
Commencer à obtenir des prédictions.
Surveiller et dépanner vos processus d'importation de données.
En savoir plus sur Tag Manager.