This article is about Google Analytics 4 properties. If you're using a Universal Analytics property, refer to the Universal Analytics section of this help center.

[GA4] About user data

Do not upload a file that includes duplicate keys. Doing so may result in inconsistent reporting data.

You can enhance user segmentation and remarketing audiences by importing user information stored outside of Analytics, such as in CRM systems. Use this import type to upload user metadata such as a loyalty rating, date of last purchase, or customer lifetime value.

How user-data import works

Implementing user-data import requires that you are able to do at least one of the following:

  • Match external data to the Client IDs (web) or the App Instance IDs (app) and Stream IDs that Analytics generates.
  • Generate unique identifiers for your users and send them to Analytics by appending the IDs to your measurement code. For example, you might derive the user ID from your website or app-authentication service, or by extracting it from your CRM system. You then add those unique identifiers (hashed for end user privacy) to your measurement code and send to Analytics with events.

The unique identifiers can be used as the key to map the user to the uploaded data.

Uploaded data is stored as user dimensions and is associated with every subsequent event triggered by the users you identify via this process. These user-dimension values can be affected after upload by collecting or uploading new values: the uploaded values are not permanent if you are also collecting values for those user dimensions in other ways.

Deleting a user data source from the data-upload service does not delete the values stored in the user dimensions for the affected users as those values may have changed. If necessary, and as with all other collection methodologies, you may need to follow up with a user deletion or data deletion to remove data uploaded via this method.

Storing user identifiers in Analytics

There are two ways to store user identifiers in Analytics:

  • Using the User ID dimension
  • Using a custom dimension with the scope set to user and with a user property to capture the user identifier

If your use case is joining CRM data to collected event data, we recommend using a custom dimension to hold the CRM ID. Using a custom dimension will prevent data collisions between IDs that you upload for user-data import and separate IDs that are implemented for the User-ID feature.

You can use the same user IDs that you maintain in your offline data source as long as these IDs do not contain any personally identifying information. Note that the Analytics terms of service, which all Analytics customers must adhere to, prohibits sending personally identifiable information (PII) to Analytics, such as names, social security numbers, email addresses, or any similar data. Learn more

Learn how to set a user ID in the Google Developer documentation.

Learn more about the User-ID feature and cross-platform reports.

Data-source details


  • Scope: the scope determines which events will be associated with the import-dimension values. There are four levels of scope: hit, session, user and product. Learn more about scope
  • Schema key: lists the key dimensions or metrics. The key is used to join the data you upload with the existing data in your events for this data-source type.
  • Imported data: lists the dimensions and metrics available for the data you upload to Analytics.

The dimensions and metrics listed for the schema are for reference only and may not be complete; the actual dimensions and metrics available will appear in the user interface when you create the data source.

Scope User
Schema key

Either of:

  • Client ID + Stream ID
  • User ID
Imported data

User properties


You may not upload or associate personally identifiable information with user-data import. Learn more


Here are example CSV templates for Client ID data and User-ID data. If you need to create your upload files by hand, use these examples as guides.

Client ID

client_id stream_id user_property1 user_property2 user_property3
1234567890.1234567890 1234567 user value 1 user value 2 user value 3
2345678901.2345678901 1234567 user value 1 user value 2 user value 3
3456789012.3456789012 1234567 user value 1 user value 2 user value 3


Make sure client IDs are stored as strings rather than numbers so they don't get truncated to fewer decimal places.


user_id user_property1 user_property2 user_property3
123abc user value 1 user value 2 user value 3
456def user value 1 user value 2 user value 3
789ghi user value 1 user value 2 user value 3


Find your stream ID

  1. Click Admin.
  2. In the Property column, use the menu to select the relevant property.
  3. Click Data Streams, then open the relevant data stream.

The Stream ID is located on the left side of the details header.

Was this helpful?
How can we improve it?
Clear search
Close search
Google apps
Main menu
Search Help Center