Send user IDs

Page Summary

outlined_flag

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

Setting custom dimensions based on user IDs leads to dimensions with too many unique values. Having too many unique values causes issues with Google Analytics data and reporting accuracy. Learn more about best practices for setting custom dimensions.

gtag.js Tag Manager

Before you begin

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

• Create a Google Analytics account and property.
• Create a web data stream for your website.
• Place the Google tag on your website.
• Have access to your website's source code.
• Have the Editor role (or above) to the Google Analytics account.

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.

To send a user ID to Analytics, add the user_id parameter to the config command on each page of your website:

if (/* your logic for determining if the user is signed in */) {
  gtag('config', 'TAG_ID', {
    'user_id': 'USER_ID'
  });
} else if (/* your logic for determining if the user signed out */) {
  gtag('config', 'TAG_ID', {
    'user_id': null
  });
} else {
  // Do nothing if the user never signed in.
}

1. Replace TAG_ID with your tag ID.
2. Replace the comments with your checks for if the user is signed-in, and if the user was signed-in but then signed out.
3. If a user is signed-in, replace USER_ID with their user ID.
4. 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".

Set user ID after initialization

In many cases, the user_id is not known when the Google tag is first initialized. For example, a user may visit your site and only log in later.

To set or update the user_id after the initial page load, use the gtag('set') command. This command sets the user_id for all subsequent events on the page and is the recommended approach instead of gtag('config') in this scenario.

Set the user ID upon login

When a user successfully logs in, call gtag('set') to associate their ID with future events:

// Example function called after successful login
function handleUserLogin(userId) {
  if (userId) {
    gtag('set', {'user_id': userId});
    console.log('User ID set for GA:', userId);

    // You can also send a login event
    gtag('event', 'login', { method: 'your_login_method' });
  }
}

// Example usage:
// handleUserLogin('12345_user');

Clear the user ID upon logout

When a user logs out, you should clear the user_id by setting its value to null:

// Example function called after logout
function handleUserLogout() {
  gtag('set', {'user_id': null});
  console.log('User ID cleared for GA.');

  // You can also send a logout event
  gtag('event', 'logout');
}

// Example usage:
// handleUserLogout();

By using gtag('set'), you make sure that the user_id is correctly managed throughout the user session, reflecting the user's current login state even if it changes after the page has loaded.