Record real-time user events

This page describes how you record real-time user events. Discovery for Media uses real-time user events to generate recommendations results. Recording as many types of user events as possible with valid document information increases the quality of your results.

For details about user events, including user event types and sample JSON for all types, see About user events.

You can record a user event in the following ways:

You can find examples of recording user events of type view-item for these methods below. For other event types, see About user events.

You can also import historical user events. It can take a considerable amount of time to record sufficient user event data to train your models. You can accelerate initial model training by importing user event data from past events in bulk. See Import historical user events.

If the user event you are recording is the first time a user is interacting with a document based on a previously provided recommendation, including an attribution token is optional but highly recommended.

User pseudo IDs are required when recording user events. For information about user pseudo IDs and user IDs, see About user information.

Before you begin

Before recording user events, you should have completed the steps in Before you begin and imported as much of your datastore as possible.

Best practices for recording user events

Discovery for Media requires high-quality data to generate high-quality results. If your data is incomplete or incorrect, the quality of your results suffers.

When you record user events, ensure that you implement the following best practices:

  • Importing as much of your datastore as possible before importing and recording events.

    Discovery for Media attempts to join recorded user events with metadata from the datastore when the user event is created. Only successfully joined events are used for training. If an event refers to a document that doesn't exist in the datastore, it is retained and Discovery for Media attempts to join it at a later time.

    If you import user events from the past, the datastore must include any documents they reference.

  • Keep your datastore up to date.

    When you record user events, the document included in the user event is connected with your current datastore. If you record an event for a document that is not in the current datastore, it cannot be used by Discovery for Media for training your models. This is called an "unjoined" event. Having a few unjoined events is expected. However, if the percentage of unjoined events reaches 5% or more of your total user events, make sure your datastore is up to date and investigate why the unjoined events are being created.

    You can see your unjoined events by using event filtering. Learn more.

  • Provide as much information with your user events as possible.

    Each user event type has different information that is required and accepted. For more information, see About user events.

  • For a bulk user event import, limit the size of the data you are importing.

    A bulk user event import can take up to 24 hours to complete.

    The size of each file must be 2 GB or smaller. You can include at most 100 files in a single import request. One approach is import only the user events for one day at a time.

  • After a bulk import, review your error reporting to ensure that your data was imported correctly.

  • When importing user event data, include an accurate timestamp for each user event and avoid importing sequential user events with identical timestamps.

    Provide the timestamp in the eventTime field in the format specified by RFC 3339.

  • If you have imported user events that are incorrect, talk to your Discovery for Media contact about how to correct the problem.

  • When possible, keep your user event data continuous.

    Gaps in user event data can reduce model quality.

  • Use a secure form of a unique identifier to keep users anonymous to Discovery Engine and protect your users' privacy. You are responsible for redacting PII (personally identifiable information), such as email or home addresses, from your data.

  • Getting the userPseudoId field correct is important. It should be consistent when recording user events, importing user events, and sending recommendation requests. Using inconsistent user pseudo IDs does not return an error, but does result in an incomplete history of user events, which can degrade the quality of model personalization.

Record user events with a JavaScript pixel

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

<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": "123"
      }
  ]
};

var _gre = _gre || {};
// Credentials for project.
_gre.apiKey = 'api-key';
_gre.logEvent = user_event;
_gre.projectId = 'project-id';
_gre.locationId = 'location-id';
_gre.dataStoreId = 'default_datastore';

(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 user events with the userEvents.write method

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

To record user events, send a POST request to the userEvents.write method and provide the appropriate request body.

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/default_data_store/userEvents:write"

Monitor import health

Recording user events successfully is important for getting high-quality results. You should monitor the event recording error rates and take action if needed.

What's next