Nutzerereignisse in Echtzeit aufzeichnen

Auf dieser Seite wird beschrieben, wie Sie Nutzerereignisse in Echtzeit aufzeichnen. Nutzerereignisse sind für Media-Apps erforderlich. Wenn Sie keine Media-Apps verwenden, ist der Import von Nutzerereignissen nicht erforderlich. Das Aufzeichnen von Nutzerereignissen wird jedoch für benutzerdefinierte Such- und Empfehlungs-Apps empfohlen.

Informationen zu den Nutzerereignistypen, die Sie aufzeichnen können, finden Sie im Feld eventType des Objekts userEvents. Wenn Sie Nutzerereignisse erfassen, können Sie die Qualität Ihrer Ergebnisse verbessern. Nutzerereignisse wirken sich beispielsweise auf das Ranking von Suchergebnissen aus. Ergebnisse mit höheren Klickraten werden hervorgehoben, während Ergebnisse mit niedrigeren Klickraten weniger sichtbar sind. Erfassen Sie keine Nutzerereignisse für Dokumente, die Sie noch nicht importiert haben.

Wenn Sie eine Such-App mit mehreren angehängten Datenspeichern verwenden, empfiehlt Google, Nutzerereignisse auf Standort- statt auf Datenspeicherebene zu erfassen. So kann ein bestimmtes Nutzerereignis an den Datenspeicher gesendet werden, mit dem es verknüpft ist. Wenn Sie Nutzerereignisse mit Dokumenten aus verschiedenen dataStores auf Standortebene statt auf Datenspeicherebene aufnehmen möchten, lesen Sie userEvents.write.

Informationen zum Bulk-Import von bisherigen Nutzerereignissen finden Sie unter Bisherige Nutzerereignisse importieren.

Sie haben folgende Möglichkeiten, Nutzerereignisse aufzuzeichnen:

Die JSON-Darstellung für Nutzerereignisse finden Sie in der API-Referenz unter userEvents.

Hinweise

Vor dem Importieren von Nutzerereignissen ist Folgendes zu beachten:

Nutzerereignisse in Echtzeit mit einem JavaScript-Pixel aufzeichnen

So zeichnen Sie Nutzerereignisse mit einem JavaScript-Pixel auf:

  1. Erstellen Sie einen API-Schlüssel für Aufrufe der Methode userEvents.collect.
  2. Ein Beispiel für ein JavaScript-Tag, mit dem Nutzerereignisse erfasst werden, finden Sie unter JavaScript-Pixel-Beispiel.

API-Schlüssel erstellen

Ein API-Schlüssel ist erforderlich, wenn Sie ein JavaScript-Pixel verwenden, um Nutzerereignisse aus den Browsern der Nutzer zu erfassen.

So erstellen Sie einen API-Schlüssel für Aufrufe der Methode userEvents.collect:

  1. Rufen Sie in der Google Cloud Console die Seite Anmeldedaten auf.

    Anmeldedaten

  2. Wählen Sie im Drop-down-Menü oben auf der Google Cloud Console-Seite Ihr Projekt aus (das Projekt ist möglicherweise bereits ausgewählt).

  3. Klicken Sie auf Anmeldedaten erstellen und wählen Sie anschließend API-Schlüssel aus. Fügen Sie keine Verweiseinschränkungen hinzu. Bei einigen Datenschutzeinstellungen für Nutzer wird die Referrer-URL nicht übergeben.

    • Notieren Sie sich den generierten API-Schlüssel, da Sie ihn beim Aufrufen des Nutzerereignis-Loggings verwenden.
  4. Für mehr Sicherheit fügen Sie Ihrem API-Schlüssel eine HTTP-Einschränkung hinzu, um den Zugriff auf den AI Applications-Dienst unter https://discoveryengine.googleapis.com/* einzuschränken.

Beispiel für ein JavaScript-Pixel

Im folgenden Beispiel wird ein view-item-Nutzerereignis mit einem JavaScript-Pixel aufgezeichnet.

Die JSON-Darstellung für Nutzerereignisse finden Sie in der API-Referenz unter userEvents.

<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>

Nutzerereignisse in Echtzeit mit der Methode userEvents.write aufzeichnen

REST

Sie können mit der Methode userEvents.write Nutzerereignisse direkt vom Backend-Server an die API senden.

Zum Aufzeichnen von Nutzerereignissen senden Sie eine POST-Anfrage an die Methode userEvents.write und geben Sie den entsprechenden Anfragetext an. Die JSON-Darstellung für Nutzerereignisse finden Sie in der API-Referenz unter userEvents.

Wenn Sie Nutzerereignisse auf Standortebene aufzeichnen, verwenden Sie den Endpunkt https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:write.

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/v1/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:write"

C#

Weitere Informationen finden Sie in der Referenzdokumentation zur AI Applications C# API.

Richten Sie zur Authentifizierung bei AI Applications Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

Weitere Informationen finden Sie in der Referenzdokumentation zur AI Applications Go API.

Richten Sie zur Authentifizierung bei AI Applications Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.


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

Weitere Informationen finden Sie in der Referenzdokumentation zur AI Applications Java API.

Richten Sie zur Authentifizierung bei AI Applications Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

Weitere Informationen finden Sie in der Referenzdokumentation zur AI Applications Python API.

Richten Sie zur Authentifizierung bei AI Applications Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

# 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

Weitere Informationen finden Sie in der Referenzdokumentation zur AI Applications Ruby API.

Richten Sie zur Authentifizierung bei AI Applications Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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