À propos des événements utilisateur

Cette page décrit les événements utilisateur pour les applications Gemini Enterprise, y compris les types d'événements utilisateur, les exigences et des exemples pour les types d'événements utilisateur.

Si vous utilisez les API Gemini Enterprise dans vos propres applications, vous devez configurer la recherche dans votre application pour obtenir les événements utilisateur, puis ajouter les données d'événements utilisateur à votre application Gemini Enterprise.

Si vous créez votre application dans laGoogle Cloud console, vous n'avez pas besoin d'importer manuellement les événements utilisateur (et vous n'avez pas besoin de lire cette page).

Pour obtenir de l'aide concernant l'enregistrement des événements utilisateur, consultez Enregistrer des événements utilisateur en temps réel. Pour importer des événements utilisateur passés de façon groupée, consultez Importer des événements utilisateur historiques.

Types d'événements utilisateur

Vous pouvez enregistrer les types d'événements utilisateur suivants lorsque les utilisateurs finaux parcourent ou recherchent votre site :

Nom de l'événement utilisateur	Action utilisateur
view-item	Affiche les détails d'un document.
search	Recherche des données dans l'application Gemini Enterprise.

Pour en savoir plus sur l'objet d'événement utilisateur, consultez la documentation de référence de l'API UserEvent.

Exemples et schémas de types d'événements utilisateur

Cette section fournit les formats de données pour chaque type d'événement compatible avec les applications Gemini Enterprise. Des exemples sont fournis pour JavaScript Pixel. Pour BigQuery, le schéma de table complet est fourni pour chaque type.

Pour tous les types d'événements utilisateur, le champ userId est facultatif.

Pour en savoir plus sur l'objet User Event, consultez la documentation de référence de l'API UserEvent.

view-item

Les lignes suivantes présentent le format de données d'événement utilisateur view-item.

Champs minimum requis pour l'objet view-item

Les exemples suivants affichent uniquement les champs obligatoires du format d'événement utilisateur view-item.

Dans la plupart des cas, documents contient les détails du document associé.

JavaScript Pixel

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "id": "document-id"
  }]
};

BigQuery

Il s'agit du schéma JSON complet pour ce type d'événement utilisateur. Spécifiez ce schéma lorsque vous créez des tables pour ce type d'événement utilisateur dans BigQuery.

Les modes des champs obligatoires sont définis sur REQUIRED ou REPEATED. Les modes des champs facultatifs sont définis sur NULLABLE.

Notez que eventTime est requis pour importer des événements avec BigQuery. eventTime est une chaîne avec un format d'horodatage.

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

Exemple d'objet view-item complet

Les exemples suivants incluent des champs obligatoires et facultatifs pour l'événement utilisateur view-item.

JavaScript Pixel

var user_event = {
  eventType: "view-item",
  userPseudoId: "visitor0",
  eventTime: "2020-01-01T03:33:33.000001Z",
  userInfo: {
    userId: "[e-mail]",
    userAgent: "Mozilla/5.0",
  },
  pageInfo: {
    pageViewId: "currentPageUri",
    uri: "http://example",
    referrerUri: "https://google",
  },
  attributionToken: "abcd",
  documents: [
    {
      id: "abcd",
    },
  ],
  tagIds: ["Treatment_B"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
  panels [
         {
           panelId: "HOME_RFY_1",
           documents: [
             {
               id: "123"
             },
             {
               id: "456"
             }
           ],
           panelPosition: 1,
           totalPanels: 2
         }
      ]
};

BigQuery

Il s'agit du schéma JSON complet pour ce type d'événement utilisateur. Spécifiez ce schéma lorsque vous créez des tables pour ce type d'événement utilisateur dans BigQuery.

Les modes des champs obligatoires sont définis sur REQUIRED ou REPEATED. Les modes des champs facultatifs sont définis sur NULLABLE.

Notez que eventTime est requis pour importer des événements avec BigQuery. eventTime est une chaîne avec un format d'horodatage.

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

search

Les lignes suivantes présentent le format d'événement utilisateur search.

Champs minimum requis pour l'objet search

Les exemples suivants affichent uniquement les champs obligatoires du format d'événement utilisateur search.

Indiquez searchQuery pour les événements de recherche où l'utilisateur a saisi une requête textuelle.

attributionToken est renvoyé avec les résultats de la requête de recherche.

documents doit inclure la liste des ID de document présentés à l'utilisateur final sur la page des résultats de recherche.

JavaScript Pixel

var user_event = {
  eventType: "search",
  userPseudoId: "user-pseudo-id",
  eventTime: "2020-01-01T03:33:33.000001Z",
  searchInfo: {
    searchQuery: "search-query",
  }, 
  attributionToken: "attribution-token",
  documents: [
    {
      id: "document-id1",
    },
    {
      id: "document-id2",
    },
  ]
};

BigQuery

Il s'agit du schéma JSON complet pour ce type d'événement utilisateur. Spécifiez ce schéma lorsque vous créez des tables pour ce type d'événement utilisateur dans BigQuery.

Les modes des champs obligatoires sont définis sur REQUIRED ou REPEATED. Les modes des champs facultatifs sont définis sur NULLABLE.

Notez que eventTime est requis pour importer des événements avec BigQuery. eventTime est une chaîne avec un format d'horodatage.

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "searchInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "searchQuery",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageCategory",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

À propos des informations utilisateur

userPseudoId représente l'identifiant d'utilisateur unique et est requis lorsque vous enregistrez un événement utilisateur.

Les informations sur les utilisateurs (UserInfo) incluses lorsque vous enregistrez un événement utilisateur contiennent la valeur userPseudoId et, si elle est disponible, la valeur userId. userId est facultatif et peut être utilisé comme identifiant unique et persistant pour un utilisateur sur tous les appareils, chaque fois que ce dernier se connecte à votre site. Lorsque vous enregistrez le userId d'un utilisateur, les applications Gemini Enterprise peuvent générer des résultats plus personnalisés pour un utilisateur sur plusieurs appareils, tels qu'un appareil mobile et un navigateur Web.

Remarque : Utilisez un identifiant unique sécurisé pour préserver l'anonymat et la confidentialité des utilisateurs de Gemini Enterprise. Vous êtes responsable du masquage des informations permettant d'identifier personnellement un utilisateur (adresse e-mail ou adresse personnelle, par exemple) dans vos données.

À propos de l'horodatage

Lorsque vous enregistrez un événement utilisateur, veillez à inclure un horodatage précis de l'événement. Des codes temporels précis permettent de s'assurer que vos événements sont stockés dans le bon ordre. Les codes temporels sont enregistrés automatiquement pour les événements collectés à l'aide du pixel JavaScript. Lorsque vous importez des événements, vous devez spécifier l'horodatage dans le champ eventTime au format indiqué par RFC 3339.