Recording user events

This page describes how you record user events. Recommendations AI uses real-time user events to generate next-item recommendations. Recording as many types of user events as possible with valid product information increases the recommendation quality.

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

You can record a user event in multiple ways:

You can find examples of recording user events of type detail-page-view for all of these methods below. For other event types, see User events.

You can also import user events in bulk. Learn more.

If the user event you are recording is the first time a user is interacting with a product based on a previously provided recommendation, including a recommendation token enables Recommendations AI to provide recommendation performance metrics, but the recommendation token is optional. For information about how to work with recommendation tokens, see Recommendation tokens.

For more information about the userInfo field, see About the user information object.

Before you begin

Before recording user events, you should have:

  • A Google Cloud project created, with authentication set up and a valid API key.

    For more information, see Before you begin.

Best practices for recording user events

Recommendations AI requires high-quality data to make high-quality predictions. If your data is incomplete or incorrect, the quality of your predictions suffers.

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

  • If you record user events before or while importing your catalog, rejoin any events recorded before the catalog import completed.

    You can import the catalog to Recommendations AI before, after, or at the same time you record user events. Doing these tasks in parallel can save time if the catalog is large and there are many user events. Once the catalog import is complete, you must use the API to rejoin events that were uploaded before the import completed.

    Recommendations AI attempts to join recorded user events with metadata from the product catalog when the user event is created. Only successfully joined events are used for training, so make sure to rejoin any events recorded before the catalog was completely imported. If an event refers to an item that doesn't exist in the catalog, it is discarded or not associated with the correct products. Similarly, if you import user events from the past, the catalog must include any products they reference; you can mark older products as OUT_OF_STOCK rather than removing them from the catalog.

  • Keep your catalog up to date.

    When you record user events, the catalog item included in the user event is connected with your current catalog. If you record an event for a catalog item that is not in the current catalog, it cannot be used by Recommendations AI for training your models. This is called an "unjoined" event. If you recorded events before your catalog was completely imported, you must rejoin the events that were recorded during the import. 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 catalog is up to date, rejoin events that were recorded before the catalog was fully updated, and investigate why the unjoined events are being created.

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

  • Make sure that you 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 User events.

  • Set up alerts so that you will know if your user event recording processes experience any outages.

  • 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 Recommendations AI 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 Recommendations AI and protect your users' privacy. You are responsible for redacting PII (personally identifiable information), such as email or home addresses, from your data.

Recording user events with a JavaScript pixel

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

<script type="text/javascript">
var user_event = {
  "eventType" : "detail-page-view",
  "userInfo": {
      "visitorId": "visitor-id",
      "userId": "user-id"
      },
  "eventDetail" : {
    "recommendationToken": "recommendation-token",
    "experimentIds": "experiment-id"
  },
  "productEventDetail": {
     "productDetails": [
        {
          "id": "123",
          "originalPrice": 140.00,
          "displayPrice": 130.00,
          "currencyCode":"USD"
        }
      ]
    }
};

var _gre = _gre || [];
// Credentials for project.
_gre.push(['apiKey', 'api-key']);
_gre.push(['logEvent', user_event]);
_gre.push(['projectId', 'project-id']);
_gre.push(['locationId', 'global']);
_gre.push(['catalogId', 'default_catalog']);
_gre.push(['eventStoreId', 'default_event_store']);

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

</script>

If you imported user events with Google Analytics 360, set userInfo.visitorID to the Google Analytics client ID. Note that the Google Analytics client ID is only part of the full _ga cookie name (for example, client ID 123456789.123456789 is part of _ga cookie GA1.3.123456789.123456789).

For more about getting the client ID, see the Google Analytics documentation.

The following is an abbreviated example that shows the format for setting the client ID in a user event. Replace "UA-XXXXXX-N" with your Google Analytics tracking ID.

<script type="text/javascript">
var tracker = ga.getByName('UA-XXXXXX-N');
var user_event = {
  "userInfo": {
      "visitorId": tracker.get('clientId'),
  }
};
</script>

Recording user events with the eventStores.userEvents.write method

You can use the eventStores.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 eventStores.userEvents.write method and provide the appropriate request body.

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     --data "{
         'eventType': 'detail-page-view',
         'userInfo': {
           'visitorId': 'visitor-id',
           'userId': 'user-id',
           'ipAddress': '0.0.0.0',
           'userAgent': 'Mozilla/5.0 (Windows NT 6.1)'
         },
         'eventDetail': {
           'recommendationToken': 'recommendation-token',
           'experimentIds': 'experiment-id'
  },
  'productEventDetail': {
    'productDetails': [{
      'id': '123',
      'originalPrice': 140.00,
      'displayPrice': 130.00,
      'currencyCode':'USD'
    }]
  }
}"
"https://recommendationengine.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/catalogs/default_catalog/eventStores/default_event_store/userEvents:write?key=api-key"

Recording user events with Google Tag Manager

Use this one-time procedure to set up a Recommendations AI tag in Tag Manager for recording user events.

First, create the tag. Then attach triggers to the tag for user events that Recommendations AI models needs to know about, and set up a variable that sets the Recommendations AI visitorId field to the user session ID.

Create a Google Tag Manager tag

Set up a tag in Tag Manager to send user event information to the Recommendations AI API.

  1. Log in to Tag Manager and select the container for your site.

  2. Go to the Tags tab and click New to add a new tag.

  3. Give your tag a name at the top of the panel (the placeholder is Untitled Variable), such as "Recommendations AI".

  4. Click Tag Configuration and choose the Recommendations AI tag to open the tag configuration panel.

  5. Enter your API key.

    Use the key you created when setting up Recommendations AI.

    Your API keys are available from the APIs & Services > Credentials page in Google Cloud console. Do not use any API key that you registered with Recommendations AI for prediction calls.

  6. Enter the project number of the Google Cloud project where Recommendations is enabled.

    The project number is available from your Google Cloud console dashboard.

  7. For the User Event Data Source field:

    • Ecommerce Data Layer: Select if you have Enhanced Ecommerce implemented via Tag Manager. This enables you to reuse the Enhanced Ecommerce data layer as your events data source instead of populating a new one.

      You can only record add-to-cart, purchase-complete, and detail-page-view events via this data source.

    • AUTOML Data Layer: Select if you are not using Google Analytics, and can manually populate data layer code. See the Tag Manager Developer Guide.

    • Ecommerce Variable: Select if you aren't using Enhanced Ecommerce in your data layer, and can't manually populate the data layer code.

      In the Read Ecommerce Data from User Variable field that appears, choose a variable. This enables Recommendations AI to read Enhanced Ecommerce user event data from a custom variable that you create.

      The variable should match the format documented in the Enhanced Ecommerce Developer Guide. To construct a variable in the correct format, you can use Enhanced Ecommerce Object Builder, a custom variable template from the Tag Manager community template gallery. Community templates are not maintained by Google. To use this template, see the Enhanced Ecommerce Object Builder gallery page for documentation and other resources.

  8. Click Save.

    Your Recommendations AI tag is created.

Next, create event triggers for your tag.

Create event triggers for your Tag Manager tag

Create triggers for all user event types your Recommendations AI models will use.

Tag Manager tags must have triggers that controls when the tag should be "fired" on the site. Triggers listen for when events occur (such as a user viewing the home page or adding an item to their cart) and prompts your tag to send that user event information to the Recommendations AI API.

You'll usually set the tag to trigger when a user views any page that has the events needed for Recommendations AI (such as the home page, product detail pages, cart pages, or checkout complete page). In these cases, the tag should fire after the page has loaded, so that cookies are available and all data layer variables are populated. To accomplish this, set your triggers to fire on Window Loaded or DOM Ready.

In some cases, you'll fire the tag when an action is performed rather than at page load (such as if a user adding an item to a cart doesn't force a page to reload).

Reuse Enhanced Ecommerce triggers

If you have implemented Enhanced Ecommerce via Tag Manager, reuse event triggers from your Enhanced Ecommerce for Recommendations AI.

You can only record add-to-cart, purchase-complete, and detail-page-view events via this data source.

Before you start these steps, make sure you have first:

  • Set up a tag in Tag Manager of tag type Google Analytics - Universal Analytics and enabled Enhanced Ecommerce on it. See the Tag Manager documentation and the Enhanced Ecommerce Developer Guide for details.
  • Configured your Enhanced Ecommerce tag in Tag Manager to trigger on the user events you plan to record for Recommendations AI.
  • Created a Recommendations AI tag in Tag Manager, with Enhanced Ecommerce as the user event data source (see Create a Tag Manager tag.

To reuse Enhanced Ecommerce triggers:

  1. On the Tag Manager, Tags page, click your Enhanced Ecommerce tag (tag type Google Analytics - Universal Analytics) to edit it.

  2. Under Advanced Settings > Tag Sequencing, select Fire a tag after <Enhanced Ecommerce tag name> fires.

  3. Select your Recommendations AI tag as the Cleanup Tag.

    Select Don't fire <Recommendations AI tag name> if <Enhanced Ecommerce tag name> fails or is paused.

  4. Save your tag.

To finalize your tag setup, overwrite the visitorID field with a variable in Tag Manager so that Recommendations AI can use session IDs to track users.

Create new triggers for your Tag Manager tag

If you don't use Enhanced Ecommerce, create new event triggers for any user events your Recommendations AI models need. Then, associate your new triggers with the Recommendations AI tag you created in Tag Manager.

Before you start these steps, make sure you have created a Recommendations AI tag in Tag Manager. See Create a Tag Manager tag.

First, create triggers. Repeat this procedure for all user events your Recommendations AI models require:

  1. On the Tag Manager, Triggers page, click New > Trigger Configuration.

  2. Choose the trigger type that applies to the user event you're creating a trigger for.

    Tag Manager provides some standard triggers. For example, Window Loaded is a trigger for detail-page-view events. For details about each type, see Trigger types.

    For some user events, you must create a custom trigger. Generally, you create a custom trigger in Tag Manager using the user event name. If you can't modify your front-end code, you can create a custom trigger using JavaScript macros.

    For more information about custom triggers, see Custom event trigger.

  3. Save your trigger.

Next, associate your new triggers with your Recommendations AI tag. This is a one-time procedure:

  1. On the Tag Manager, Tags page, click your Recommendations AI tag to edit it.

  2. Click Triggering, select your new triggers, and click Add.

  3. Save your tag.

Next, set up a variable that sets the Recommendations AI visitorId field to the user session ID.

Setting the visitorID field in Tag Manager

Recommendations AI uses the value visitorId to track users. visitorId is typically a session ID, and is required for all events. Set up a variable that sets session IDs as visitorId.

This procedure assumes you are using Google Analytics. If you aren't, you can use another cookie or variable, or get the visitor ID from the automl data layer.

Before starting these steps, make sure you have already created a Recommendations AI tag in Tag Manager (see Recording user events > Tag Manager).

To set the visitorID value to a variable for the Recommendations AI tag:

  1. In Tag Manager, go to the Variables tab and click New to create a new user-defined variable.

  2. Give the variable a name at the top of the dialog, such as "GA visitorId".

  3. Enter your variable settings.

    You can use the client ID or the cookie ID to set as the source of visitor IDs. Always use a consistent visitor ID source when ingesting historical and real-time user events.

    Client ID

    In Google Analytics 360 BigQuery, this variable maps to the clientID field described in the Google Analytics documentation for the Universal Analytics BigQuery export schema. In Google Analytics 4, this variable maps to the user_pseudo_id field described in the Google Analytics documentation for the Google Analytics 4 BigQuery export schema.

    1. Set Variable Type to Custom JavaScript.

    2. Enter the following script in the Custom JavaScript field.

      Replace "UA-XXXXXX-N" with your Google Analytics tracking ID. To find your tracking ID, see What happened to my Tracking ID? For more about getting the client ID, see the Google Analytics documentation.

      function() {
 var tracker = ga.getByName('UA-XXXXXX-N');
 return tracker.get('clientID');
}

    3. Click Save to save the variable.

    1. Choose 1st Party Cookie as the variable type.

    2. In the Cookie Name field, enter _ga.

    3. Click Format Value, select Convert undefined to.., and enter "" (an empty string).

    4. Click Save to save the variable.

      This maps the first party cookie "_ga" to a Tag Manager variable called "GA visitorId".

  4. Go to the Tags tab and click your Recommendations tag to edit it.

  5. Click Tag Configuration and, under Fields to Overwrite, click the + Overwrite a value on the UserEvent message button.

  6. Select userInfo.visitorId as the field, and the variable you just created as the field value.

  7. Save your Recommendations tag.

Next, set up monitoring of event recording errors and other issues to make sure Recommendations AI keeps receiving data successfully.

If you're using automl data layer as your user event source, make sure to also set up your data layer.

Using the automl data layer with Tag Manager

If you created your Recommendations AI tag in Tag Manager to use the automl data layer as the user event source, set up the dataLayer variable in your source HTML as described in the Tag Manager Developer Guide.

Some fields like userInfo.visitorId are required for the UserEvent message, but might not be available when populating the data layer. For example, userInfo.visitorId might be derived from the user's cookie, or eventDetail.experimentIds from the A/B experimentation framework. In this case, you overwrite the field on the Tag Manager tag directly from a variable.

You can overwrite the following fields:

  • userInfo.visitorId
  • userInfo.userId
  • eventDetail.recommendationToken
  • eventDetail.experimentIds

For how to overwrite a UserEvent field in Tag Manager, see Setting the visitorID field in Tag Manager, which walks through overwriting the userInfo.visitorId field value with a user-defined variable.

The following example shows the data layer that needs to be included in your page for a detail-page-view UserEvent using Tag Manager:

<script>
  dataLayer = dataLayer || [];
  dataLayer.push({
    'automl': {
      'eventType' : 'detail-page-view',
      'userInfo': {
        // In most cases, the user and visitor ID fields can be populated
        // from a client side JavaScript variable, for example a cookie.
        // If you set the user and/or visitor ID values from the server,
        // populate the `userId` and/or `visitorId` fields here.
      },
      'eventDetail': {
        'recommendationToken': 'recommendation-token'
        // In most cases, the experiment ID field is populated from a
        // client side JavaScript variable as defined by the experiment
        // manager.
        // If you set the experiment ID value from the server,
        // populate the `experimentIds` field here.
      },
      'productEventDetail': {
         'productDetails': [{
           'id': '123',
           'originalPrice': 140.00,
           'displayPrice': 130.00,
           'currencyCode':'USD'
          }
        ]
      }
    },
    // You can use the 'automl' data layer element along with other
    // data layer elements.
    'ecommerce': {
      ...
    },
  }];
</script>

Monitoring import health

Recording user events successfully is important for getting high-quality recommendations. You should monitor the event recording error rates and take action if needed. For more information, see Setting up alerts for data upload issues.

What's next