Send user IDs

  • User IDs are unique identifiers assigned to individual users to connect their behavior across different sessions, devices, and platforms in Google Analytics.

  • Do not set custom dimensions based on user IDs as this can cause issues with data and reporting accuracy due to too many unique values.

  • Before sending user IDs, ensure you have a Google Analytics account and property, a web data stream, the Google tag on your website, access to the source code, and the Editor role or above.

  • Send the user's ID if they are signed-in, do not send the parameter if they have never signed in, and send null if they were signed-in but then signed out.

  • To send a user ID using gtag.js, add the user_id parameter to the config command on each page of your website, replacing <var translate="no">TAG_ID</var> with your tag ID and implementing logic to determine the user's sign-in status.

User IDs are your own unique identifiers that you assign to individual users. This guide explains how to send user IDs to Google Analytics, so you can connect user behavior across different sessions, devices, and platforms.

To learn more about the User-ID feature, see Measure activity across platforms. To learn how to set a user ID for an app, see Set a user ID.

The user_id parameter is a configuration parameter, not a custom user property or standard event parameter. Instead, user_id is a reserved system parameter used specifically to identify authenticated users across devices and sessions. Don't set it as a custom user property (for example, in the user_properties object for gtag.js or in the User Properties section of Google Tag Manager tags), and don't register it as a custom dimension in the Analytics UI. Likewise, don't pass it as an event-level parameter on individual events. Instead, set user_id only as a configuration parameter using the following methods.


Before you begin

Before you can send user IDs, make sure you've completed the following:

Send user IDs

The value you send for user_id depends on the state of the user:

  • User has never signed in: Don't send the user_id parameter.
  • User is signed-in: Send their user ID.
  • User was signed-in, then signed out: Send null.

Step 1: Update your data layer

Before you send user IDs to Analytics, make the user_id available in your data layer on your website.

You can update the data layer during the initial page load or after the page has loaded (for example, when a user logs in). Each time you call dataLayer.push, any associated Tag Manager tags will receive the updated user_id.

Key Point: To ensure the user_id is associated with the initial page view event and all subsequent events, you must declare your data layer and push the user_id above (before) the Google Tag Manager container snippet on the page. If the user_id is pushed after the GTM snippet, it won't be available when your tags fire on the container load event.

if (/* your logic for determining if the user is signed in */) {
  dataLayer.push({
    'user_id': 'USER_ID'
  });
} else if (/* your logic for determining if the user signed out */) {
  dataLayer.push({
    'user_id': null
  });
} else {
  // Do nothing if the user never signed in.
}
  1. Replace the comments with your checks for if the user is signed-in, and if the user was signed-in but then signed out.
  2. If a user is signed-in, replace USER_ID with their user ID.
  3. When a user signs out, set user_id to null. Don't send an empty string (""), a blank string (" "), or the quoted words "null" or "NULL".

Step 2: Create a data layer variable

  1. In Google Tag Manager, click Variables.
  2. In the User-Defined Variables section, click New.
  3. Click Variable Configuration > Data Layer Variable.
  4. Enter a name for the variable at the top.
  5. In the Data Layer Variable Name field, enter a name for your user ID variable (such as "user_id").
  6. Click Save.

Step 3: Modify your Google tag

Finally, modify the Configuration tag so all events associated with the tag use the Data Layer variable:

  1. In Tag Manager, click The Tags menu item Tags.
  2. Select your Google tag.
  3. Under Configuration settings section, add a new row with the following parameters:
    • Parameter: user_id
    • Value: Select the Data Layer variable you created.
  4. Click Save.
  5. Click Submit to publish the changes.

How User-ID is used in Google Analytics

Once you send user_id values to Google Analytics, they are used to:

  • Unify user journeys: Connect user activity across different sessions, devices, and platforms for signed-in users.
  • Improve user counts: Provide more accurate, de-duplicated user metrics.
  • Enable analysis:
    • Analyze activity based on signed-in status: Use dimensions like "Signed in with user ID" to create comparisons in standard reports or segments in Explorations.
    • Power the User Explorer exploration technique, allowing you to drill down into the timeline of activities for individual users.

Important considerations

  • Do NOT create custom dimensions for User ID: You should not register the user_id as a user-scoped custom dimension. This is a key best practice. Doing so creates an unnecessary high-cardinality dimension, which can severely impact report performance, cause data to be grouped into the "(other)" row, and consume your custom dimension quota. The built-in User-ID feature handles the user stitching. Learn more in Best practices for User-ID.

  • Set user_id as a configuration setting, not a user property or event parameter: Because user_id is a reserved system parameter, it must only be applied as a configuration or a setting parameter (using the gtag() config or set commands, or Google Tag Manager's Google tag configuration settings). Don't configure it as a custom user property, pass it inside the user_properties settings object, or send it as an event-level parameter on individual events.

  • Direct ID visibility in standard reports vs. explorations: Raw user_id values are not available as a standard dimension in standard reports or most explorations (such as Free Form) to maintain privacy and manage cardinality. However, you can view the raw user_id in the User Explorer exploration template under the column labeled Effective user ID for logged-in users.

  • Accessing raw user IDs: If you need to perform analysis using the raw user_id values, the recommended approach is to use the GA4 BigQuery Export. The user_id field is available in the exported data.

To ensure User-ID data is being used and visible in the User Explorer, make sure your property's Reporting Identity is set to Blended or Observed.

Previous
Add parameters
Next
Measure exceptions