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 à la fois aux recommandations et à la recherche. Une fois que vous avez enregistré des données, les deux services peuvent utiliser ces événements. Vous n'avez donc pas besoin d'importer les mêmes données deux fois si vous utilisez les deux services.

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

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

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

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

Si l'événement utilisateur que vous enregistrez est la première interaction d'un utilisateur avec un produit sur la base d'une recommandation ou de résultats de recherche fournis précédemment, l'inclusion d'un jeton d'attribution permet de fournir des métriques de performances. Vous devez inclure un jeton d'attribution pour Vertex AI Search pour le commerce au travail. Pour en savoir plus sur l'utilisation des jetons d'attribution, consultez la section Jetons d'attribution.

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

É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 ne figurant pas dans le catalogue actuel, il ne peut pas être utilisé pour entraîner vos modèles. C'est ce qu'on appelle un « non associé » . Si vous avez enregistré des événements avant l'importation complète de votre catalogue, vous devez réassocier les événements enregistrés lors de l'importation. Le fait d'avoir quelques événements non associés est courant. Toutefois, si le pourcentage d'événements non associés atteint ou dépasse 5 % de votre nombre total d'événements utilisateur, vérifiez que votre catalogue est à jour, réassociez les événements enregistrés avant la mise à jour complète du catalogue, et tentez de trouver ce que entraîne la création d'événements non associés.

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

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

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

  • Configurez des alertes Cloud Monitoring pour savoir si 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 inférieure ou égale à 2 Go. 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 for retail pour savoir comment corriger le problème.

  • Dans la mesure du possible, maintenez les données de vos événements utilisateur continues.

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

  • Utilisez une forme sécurisée d'identifiant unique pour préserver l'anonymat des utilisateurs 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. Remplacez "G-XXXXXX" par votre ID de suivi Google Analytics.

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

Enregistrer des événements utilisateur 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énements utilisateur que vous souhaitez importer sont correctement formatées.

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

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

Vérifiez les points suivants :

  1. Si vous importez des événements d'achat, 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.

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

  1. Par la suite, pour faciliter l'encodage des URL, vous pourrez définir GA4_EVENT comme variable contenant des données d'événement. Cet exemple montre un événement add-to-cart.

    GA4_EVENT='{
  "event_timestamp": 1622994083878241,
  "event_name": "add_to_cart",
  "user_pseudo_id": "352499268.1622993559",
  "items": [
    {
      "item_id": "11",
      "price": 29.99,
      "quantity": 3
    }
  ],
  "event_params": [
    {
      "key": "currency",
      "value": {
        "string_value": "CAD"
      }
    }
  ],
  "user_id": "Alice"
}'

  2. 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 des événements utilisateur avec Google Tag Manager

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

Certaines décisions à prendre pendant la configuration varient selon que vous utilisez Google Analytics et Google Analytics E-commerce. L'e-commerce Google Analytics peut être implémenté à l'aide de Google Analytics 4 ou de l'e-commerce amélioré. 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 pour Google Analytics qui transmet les titres, les ID, les prix, les détails des transactions et d'autres données d'e-commerce structurées à Google Analytics. Vertex AI Search pour le commerce peut utiliser automatiquement la solution d'e-commerce Google Analytics couche de données. Si vous l'avez déjà fait, la configuration peut donc ê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 :

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

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

  3. Saisissez les paramètres de votre variable.

    Vous pouvez utiliser l'ID client ou l'ID de cookie pour définir la source 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, cette variable est mappée sur le champ clientID dans le schéma d'exportation BigQuery pour Universal Analytics. Dans Google Analytics 4, cette variable correspond au champ user_pseudo_id dans le schéma d'exportation BigQuery pour Google Analytics 4.

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

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

      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.

    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.

  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), telle que "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 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.

  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 votre console Google Cloud.

  7. 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. Il utilise le schéma Google Analytics 4, le cas échéant. Sinon, il utilise l'e-commerce amélioré UA. Avec cette source de données, vous ne pouvez enregistrer que des événements add-to-cart, purchase-complete, detail-page-view et search. search événements sont enregistrés avec d'impressions e-commerce combiné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 une variable 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. Cela permet à Vertex AI Search for retail de lire les données d'événement utilisateur de l'e-commerce Google Analytics à partir d'une variable personnalisée que vous créez.

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

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

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

  10. Cliquez sur Enregistrer.

    Votre tag Cloud Retail est créé.

Anciennes options de sources de données

Auparavant, les 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 dans les nouvelles balises. 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 d'une édition à une autre :

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

  • Si vous avez utilisé 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.

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 associez-le à votre tag Cloud Retail. Cela permet à Vertex AI Search pour le commerce d'obtenir des requêtes de recherche à partir d'Analytics.

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

  • Variable – E-commerce ou la couche de données avec le schéma d'e-commerce Google Analytics : créez une variable d'élément URL ou DOM dans Tag Manager, puis associez-la à votre balise Cloud Retail. En outre, activez l'option permettant à votre tag d'utiliser les impressions d'e-commerce Google Analytics pour créer des événements de recherche.
  • Variable – Cloud Retail ou une couche de données renseignée manuellement : créez une variable d'élément URL ou DOM dans Tag Manager, puis associez-la à votre balise Cloud Retail. 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). La méthode que vous créez et la configuration dépendent de la mise en œuvre de votre site :

  • Une variable d'URL récupère les requêtes de recherche à partir des URL de résultats de recherche de votre site. Utilisez cette variable si votre site inclut la chaîne de requête dans l'URL de ses résultats de recherche.
  • Une variable Élément DOM récupère les informations de requête de recherche à partir du DOM (Document Object Model) de votre site. Vous n'avez pas besoin de modifier le DOM pour utiliser cette variable. Toutefois, vous devez pouvoir lire et comprendre le DOM pour configurer correctement cette variable.
  • Une variable JavaScript personnalisée renvoie des données formatées par un . Cela est utile si vous avez des données existantes que vous souhaitez mettre en forme dans le schéma Cloud Retail ou Ecommerce.

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

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

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

  3. Saisissez les paramètres de la variable :

    Type "URL"

    1. Définissez Type de variable sur URL.

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

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

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

    Type "Élément DOM"

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

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

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

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

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

    Type JavaScript personnalisé

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

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

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

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

      function () {

  var retail;
  var items = [];

  for (var i = 0; i < {{Ecommerce Items}}.length; i++) {
    var item = {'product':
                {
                  'id': {{Ecommerce Items}}[i].item_id
                }
               };

    items.push(item);
  }

  retail = {
    'eventType': 'search',
    'searchQuery': '{{Search Query}}',
    'filter': '{{Search Filter}}',
    'productDetails': items
  }

  return retail;
}

  4. Cliquez sur Enregistrer pour enregistrer la variable.

Associez ensuite la variable à votre tag Cloud Retail :

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

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

    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.

  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 couche de données renseignée manuellement comme source d'événements utilisateur pour votre environnement Cloud Retail .

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

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

Commencez par créer une variable de type constante :

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

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

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

  4. Saisissez search dans le champ Valeur.

  5. Cliquez sur Enregistrer pour enregistrer la variable.

Associez ensuite la variable à votre tag Cloud Retail :

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

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

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

  4. Enregistrez votre tag.

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

Créer des déclencheurs d'événements pour votre 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.

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

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

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

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

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

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

Créer des déclencheurs pour votre 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 requis par vos modèles Vertex AI Search pour le commerce :

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

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

  3. Enregistrez votre déclencheur.

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

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

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

  3. Enregistrez votre tag.

Ensuite, prévisualisez votre balise. 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 les déclencheurs d'e-commerce Google Analytics

Si vous avez mis en œuvre l'e-commerce Google Analytics via Tag Manager, réutilisez les déclencheurs d'événement de votre e-commerce Google Analytics pour la recherche Vertex AI pour le retail.

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

Le tableau suivant montre comment les 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 (si combiné au 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. Pour en savoir plus, consultez la documentation Tag Manager, le guide du développeur GA4 ou le guide du développeur d'e-commerce amélioré.
  • Configuré votre tag d'e-commerce amélioré ou GA4 dans Tag Manager pour qu'il se déclenche en fonction des événements utilisateur que vous prévoyez d'enregistrer pour Vertex AI Search pour le commerce.
  • 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:

  1. Sur la page Tags 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 <Nom de la balise GA4 ou de l'e-commerce amélioré> incendies.

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

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

  4. Enregistrez votre tag.

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

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

Utiliser la couche de données cloud_retail avec Tag Manager

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

À propos de la couche de données

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

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

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

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

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

Champs obligatoires dans la couche de données cloud_retail

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

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

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

Vous pouvez écraser les champs suivants :

  • visitorId
  • userInfo.userId
  • attributionToken
  • experimentIds

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

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

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

Prévisualiser votre balise Tag Manager

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

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

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

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

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

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

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

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

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

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

Rechercher les erreurs de balise

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

Vous pouvez 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.

  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 conteneur unique côté serveur avec de nombreux clients en aval. Cela crée une seule source de vérité côté client, avec de nombreux consommateurs côté serveur. Cette architecture libère la charge sur le Web et dans le serveur, ce qui est intéressant pour les utilisateurs qui souhaitent 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 sa propre balise côté serveur native.

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

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

La principale différence entre la version serveur et la version Web de la balise Cloud Retail est que vous ne pouvez pas définir la source de données. La source de données 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 mettre jusqu'à 24 heures à s'afficher après l'ingestion des données.

Accéder à la page "Données"

Étape suivante