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

Cette page explique comment enregistrer des événements utilisateur en temps réel. Les événements utilisateur sont requis pour les recommandations multimédias. Si vous n'utilisez pas les recommandations multimédias, l'importation d'événements utilisateur n'est pas nécessaire. Toutefois, l'enregistrement des événements utilisateur est recommandé pour les applications de recherche multimédia.

Pour connaître les types d'événements utilisateur que vous pouvez enregistrer, consultez le champ eventType de l'objet userEvents. En insérant des événements utilisateur, vous pouvez améliorer la qualité de vos recommandations et le classement de vos résultats de recherche. Les résultats avec des taux de clics plus élevés sont mis en avant, tandis que ceux avec des taux de clics plus faibles sont masqués. N'enregistrez pas d'événements utilisateur pour les documents que vous n'avez pas encore importés.

Si vous utilisez une application de recherche avec plusieurs datastores associés, Google vous recommande d'ingérer les événements utilisateur au niveau de la zone géographique plutôt qu'au niveau du data store. Cela permet d'envoyer un événement utilisateur donné au data store auquel il est associé. Pour ingérer des événements utilisateur avec des documents provenant de différents dataStores au niveau de l'emplacement plutôt qu'au niveau du data store, consultez userEvents.write.

Pour importer des événements utilisateur historiques de manière groupée, consultez Importer des événements utilisateur historiques.

Vous pouvez enregistrer des événements utilisateur de différentes manières:

• Avec un pixel JavaScript
• Avec la méthode userEvents.write.

Pour connaître la représentation JSON des événements utilisateur, consultez userEvents dans la documentation de référence de l'API.

Remarque :Le widget ne peut pas enregistrer les événements utilisateur.

Avant de commencer

Avant d'importer des événements utilisateur:

• Créez un data store et une application.
• Consultez À propos des événements utilisateur pour connaître les exigences concernant les événements utilisateur.

Enregistrer des événements utilisateur en temps réel avec un pixel JavaScript

Pour enregistrer des événements utilisateur avec un pixel JavaScript:

1. Créer une clé API pour les appels à la méthode userEvents.Collect
2. Consultez Exemple de pixel JavaScript pour voir un exemple de balise JavaScript qui collecte des événements utilisateur.

Créer une clé API

Une clé API est requise si vous utilisez un pixel JavaScript pour collecter des événements utilisateur à partir des navigateurs des utilisateurs.

Pour créer une clé API pour les appels à la méthode userEvents.Collect, procédez comme suit:

1. Dans la console Google Cloud, accédez à la page Identifiants.

   Identifiants

2. Dans la liste déroulante de projet en haut de la page Google Cloud Console, sélectionnez votre projet (il est peut-être déjà sélectionné).

3. Cliquez sur Créer des identifiants, puis sélectionnez Clé API. N'ajoutez aucune restriction de référent. Certains paramètres de confidentialité de l'utilisateur ne transmettent pas l'URL de provenance.

   • Prenez note de la clé API générée, que vous utiliserez lors des appels à l'API de journalisation des événements utilisateur.

4. Pour renforcer la sécurité, ajoutez une restriction HTTP à votre clé API afin de restreindre l'accès au service Vertex AI Agent Builder à l'adresse https://discoveryengine.googleapis.com/*.

Remarque :La clé API ne sert qu'à authentifier la méthode userEvents.Collect et la méthode servingConfigs.searchLite. Les autres méthodes de Vertex AI Agent Builder nécessitent OAuth 2.0 via un compte de service ou un compte utilisateur.

Exemple de pixel JavaScript

L'exemple suivant enregistre un événement utilisateur view-item à l'aide d'un pixel JavaScript.

Pour connaître la représentation JSON des événements utilisateur, consultez userEvents dans la documentation de référence de l'API.

<script type="text/javascript">
var user_event = {
  "eventType" : "view-item",
  "userPseudoId": "USER_PSEUDO_ID",
  "userInfo": {
      "userId": "USER_ID"
  },
  "attributionToken": "ATTRIBUTION_TOKEN",
  "tagIds": "TAG_ID",
  "documents": [
      {
        "id": "DOCUMENT_ID"
      }
  ]
};

var _gre = _gre || {};
// Credentials for project.
_gre.apiKey = '[API_KEY]';
_gre.logEvent = user_event;
_gre.projectId = 'PROJECT_ID';
_gre.locationId = 'LOCATION_ID';
_gre.dataStoreId = 'DATA_STORE_ID';

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

</script>

Enregistrer des événements utilisateur en temps réel à l'aide de la méthode userEvents.write

REST

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é. Pour la représentation JSON des événements utilisateur, consultez userEvents dans la documentation de référence de l'API.

Si votre application comporte plusieurs data stores, Google vous recommande d'ingérer les événements au niveau de la localisation. Dans ce cas, utilisez le point de terminaison https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:write.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data "{
         'eventType': 'view-item',
         'userPseudoId': 'visitor0',
         'eventTime': '2020-01-01T03:33:33.000001Z',
         'tagIds': ['321'],
         'attributionToken': 'ABC',
         'attributes': {
            'example_text_attribute': {
              'text': ['text_1', 'text_2']
            },
            'example_number_attribute': {
               'numbers': [3.14, 42, 1.2345]
            }
         },
         'documents': [{
            'id': 'abc'
          }],
         'userInfo': {
           'userId': 'abc',
           'userAgent': 'Mozilla/5.0'
         },
         'pageInfo': {
          'uri': 'http://example',
          'referrerUri': 'http://example',
          'pageViewId': 'currentPageUri'
        }
}" \\
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:write"

C#

Pour en savoir plus, consultez la documentation de référence de l'API C# de Vertex AI Agent Builder.

Pour vous authentifier auprès de Vertex AI Agent Builder, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

using Google.Cloud.DiscoveryEngine.V1;

public sealed partial class GeneratedUserEventServiceClientSnippets
{
    /// <summary>Snippet for WriteUserEvent</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void WriteUserEventRequestObject()
    {
        // Create client
        UserEventServiceClient userEventServiceClient = UserEventServiceClient.Create();
        // Initialize request argument(s)
        WriteUserEventRequest request = new WriteUserEventRequest
        {
            ParentAsDataStoreName = DataStoreName.FromProjectLocationDataStore("[PROJECT]", "[LOCATION]", "[DATA_STORE]"),
            UserEvent = new UserEvent(),
            WriteAsync = false,
        };
        // Make the request
        UserEvent response = userEventServiceClient.WriteUserEvent(request);
    }
}

Go

Pour en savoir plus, consultez la documentation de référence de l'API Go de Vertex AI Agent Builder.

Pour vous authentifier auprès de Vertex AI Agent Builder, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewUserEventClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.WriteUserEventRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#WriteUserEventRequest.
	}
	resp, err := c.WriteUserEvent(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

Pour en savoir plus, consultez la documentation de référence de l'API Java de Vertex AI Agent Builder.

Pour vous authentifier auprès de Vertex AI Agent Builder, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

import com.google.cloud.discoveryengine.v1.DataStoreName;
import com.google.cloud.discoveryengine.v1.UserEvent;
import com.google.cloud.discoveryengine.v1.UserEventServiceClient;
import com.google.cloud.discoveryengine.v1.WriteUserEventRequest;

public class SyncWriteUserEvent {

  public static void main(String[] args) throws Exception {
    syncWriteUserEvent();
  }

  public static void syncWriteUserEvent() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (UserEventServiceClient userEventServiceClient = UserEventServiceClient.create()) {
      WriteUserEventRequest request =
          WriteUserEventRequest.newBuilder()
              .setParent(
                  DataStoreName.ofProjectLocationDataStoreName(
                          "[PROJECT]", "[LOCATION]", "[DATA_STORE]")
                      .toString())
              .setUserEvent(UserEvent.newBuilder().build())
              .setWriteAsync(true)
              .build();
      UserEvent response = userEventServiceClient.writeUserEvent(request);
    }
  }
}

Python

Pour en savoir plus, consultez la documentation de référence de l'API Python de Vertex AI Agent Builder.

Pour vous authentifier auprès de Vertex AI Agent Builder, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1


def sample_write_user_event():
    # Create a client
    client = discoveryengine_v1.UserEventServiceClient()

    # Initialize request argument(s)
    request = discoveryengine_v1.WriteUserEventRequest(
        parent="parent_value",
    )

    # Make the request
    response = client.write_user_event(request=request)

    # Handle the response
    print(response)

Ruby

Pour en savoir plus, consultez la documentation de référence de l'API Ruby de Vertex AI Agent Builder.

Pour vous authentifier auprès de Vertex AI Agent Builder, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

require "google/cloud/discovery_engine/v1"

##
# Snippet for the write_user_event call in the UserEventService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1::UserEventService::Client#write_user_event.
#
def write_user_event
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::UserEventService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1::WriteUserEventRequest.new

  # Call the write_user_event method.
  result = client.write_user_event request

  # The returned object is of type Google::Cloud::DiscoveryEngine::V1::UserEvent.
  p result
end