Record real-time user events

This page describes how to record user events in real time.

For the user event types that you can record, see the eventType field of the userEvents object. By ingesting user events, you can improve the quality of your results. For example, user events affect the ranking of search results. Results with higher click-through rates are boosted, while results with lower click-through rates are buried. Don't record user events for documents that you have not yet imported.

If you are using an app with multiple data stores attached, then Google recommends that you ingest user events at the location level instead of the data-store level. This allows a given user event to be sent to the data store that it's associated with. To ingest user events with documents from different dataStores at the location level rather than data-store level, see userEvents.write.

To import historical user events in bulk, see Import historical user events.

You can record user events in the following ways:

With a JavaScript pixel.
With the userEvents.write method.

For the JSON representation for user events, see userEvents in the API reference.

Before you begin

Before you import user events:

Create a data store and an app.
Review About user events for user event requirements.

Record real-time user events with a JavaScript pixel

To record user events with a JavaScript pixel:

Create an API key for calls to the userEvents.collect method.
See the JavaScript pixel example for an example of a JavaScript tag that collects user events.

Create an API key

An API key is required if you use a JavaScript pixel to collect user events from users' browsers.

To create an API key for calls to the userEvents.collect method, complete the following steps:

In the Google Cloud console, go to the Credentials page.

Credentials
In the project drop-down at the top of the Google Cloud console page, select your project (the project might already be selected).
Click Create credentials and then select API key. Don't add any referrer restrictions. Some user privacy settings don't pass the referrer URL.
- Take note of the generated API key, which you will use when calling user event logging.
For increased security, add an HTTP restriction to your API Key to restrict access to the Agentspace service at https://discoveryengine.googleapis.com/*.

JavaScript pixel example

The following example records a view-item user event using a JavaScript pixel.

For the JSON representation for user events, see userEvents in the API reference.

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

Record real-time user events with the `userEvents.write` method

REST

You can use the userEvents.write method to send user events directly to the API from your backend server.

To record user events, send a POST request to the userEvents.write method and provide the appropriate request body. For the JSON representation for user events, see userEvents in the API reference.

If you are recording user events at the location level, use the endpoint 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#

Before trying this sample, follow the C# setup instructions in the Agentspace quickstart using client libraries. For more information, see the Agentspace C# API reference documentation.

To authenticate to Agentspace, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

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

Before trying this sample, follow the Go setup instructions in the Agentspace quickstart using client libraries. For more information, see the Agentspace Go API reference documentation.

To authenticate to Agentspace, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.


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

Before trying this sample, follow the Java setup instructions in the Agentspace quickstart using client libraries. For more information, see the Agentspace Java API reference documentation.

To authenticate to Agentspace, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

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

Before trying this sample, follow the Python setup instructions in the Agentspace quickstart using client libraries. For more information, see the Agentspace Python API reference documentation.

To authenticate to Agentspace, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

# 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

Before trying this sample, follow the Ruby setup instructions in the Agentspace quickstart using client libraries. For more information, see the Agentspace Ruby API reference documentation.

To authenticate to Agentspace, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

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

Record real-time user events Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Record real-time user events with a JavaScript pixel

Create an API key

JavaScript pixel example

Record real-time user events with the userEvents.write method

REST

C#

Go

Java

Python

Ruby

Record real-time user events

Record real-time user events with the `userEvents.write` method