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 pour les recommandations de médias. Si vous n'utilisez pas les recommandations multimédias, l'importation d'événements utilisateur n'est pas nécessaire. Toutefois, il est recommandé d'enregistrer les événements utilisateur pour les applications de recherche de médias.

Pour connaître les types d'événements utilisateur que vous pouvez enregistrer, consultez le champ eventType de l'objet userEvents. En ingé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 affichant des taux de clics plus élevés sont boostés, tandis que ceux affichant des taux de clics plus faibles les taux de clics sont perdus. N'enregistrez pas d'événements utilisateur pour les documents que vous n'ont pas encore été importées.

Si vous utilisez une application de recherche associée à plusieurs data stores, Google recommande d'ingérer les événements utilisateur au niveau de l'emplacement au niveau du data store. Cela permet d'envoyer un événement utilisateur donné 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 datastore, consultez userEvents.write.

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

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

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

Avant de commencer

Avant d'importer des é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éez une clé API pour les appels à userEvents.Collect. méthode
  2. Consultez l'exemple de pixel JavaScript pour voir un exemple Balise JavaScript qui collecte les é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.

    Accéder à la page 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 concernant les URL de provenance. Il est connu que 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 plus de sécurité, ajoutez un Restriction HTTP à votre clé API pour restreindre l'accès au service Vertex AI Agent Builder à https://discoveryengine.googleapis.com/*.

Exemple de pixel JavaScript

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

Pour la représentation JSON des événements utilisateur, consultez la section userEvents dans consultez 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 le 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 des événements au niveau de l'emplacement. 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# Vertex AI Agent Builder.

Pour vous authentifier auprès de Vertex AI Agent Builder, configurez le service 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 les API Go de Vertex AI Agent Builder documentation de référence.

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 Vertex AI Agent Builder.

Pour vous authentifier auprès de Vertex AI Agent Builder, configurez le service 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 les API Python de Vertex AI Agent Builder documentation de référence.

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 les API Ruby de Vertex AI Agent Builder documentation de référence.

Pour vous authentifier auprès de Vertex AI Agent Builder, configurez le service 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