[GA4] Import user data

Do not upload a file that includes duplicate keys (e.g., two fields named user_id).

You can enhance user segmentation and remarketing audiences by importing user metadata that you store outside of Analytics, for example, loyalty rating, date of last purchase, and customer lifetime value from your CRM system.

How user-data import works

To successfully import user-data, you need to be able to join your data with Analytics data using one of the following keys:

  • Stream ID plus either the Client IDs (web) or the App Instance IDs (app) that Analytics generates.
  • A unique identifier that you generate for each user 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.

Analytics uses 1) the Stream IDs and Client or App Instance IDs or 2) the unique identifiers as the key to map the user to the uploaded data.

You select one of these methods when you import your data.

If you are using the stream ID plus the app instance ID to map users to uploaded data, it is important to note that a new app instance ID is assigned each time an app is installed. If a user uninstalls and re-installs an app, data collected before and after the re-install will be associated with two different app instance IDs and therefore two different users. App updates do not change the app instance ID.

Uploaded data is stored in user dimensions and after upload is associated with every subsequent event triggered by the users you identify via this process.

Storing user identifiers in Analytics

There are 2 ways to store user identifiers in Analytics:

Create the custom dimensions

You need to create the custom dimensions before you upload your data.

Create user-scoped custom dimensions for the values you want to import. For example, you might create the custom dimension "User loyalty tier" with the user property "loyalty_tier".

Once you create the custom dimensions, Analytics needs up to 4 hours before it’s ready to recognize the data you import. (You can verify that the custom dimensions are processed by opening an exploration and checking to see if the user properties are available in the dimension picker.)

Create a CSV file

Create a CSV file of user identifiers and user-property values. For example:

user_id loyalty_tier
A1234 gold
J1234 bronze
K1234 silver
R1234 silver

Upload data

The general upload procedure is outlined in About Data Import.

When you create the data source, select either User data by User ID or User data by Client ID, depending on which method you're using to identify users (User ID or Client ID/App Instance ID + Stream ID).

When you map Analytics fields to your imported fields, you'll see something like the following:


In the first column you'll see:

  • The Analytics field (in this case, User ID) on which you're joining your data. Also called the schema key.
  • User properties for the custom dimensions you created in Analytics that match the fields in your CSV. (In the preceding example, the custom dimension is "User loyalty tier" with the user property "loyalty_tier".)

In the second column, you select the matching fields in your CSV:


After you upload your data, it can take up to 24 hours for Analytics to make that data available in reports, audiences, and explorations.

  • The users you identify have to engage with your site or app after you upload the data in order for those user properties to be associated with user activity in reporting.
  • Imported user data becomes immediately available as criteria to qualify a user for an existing GA4 audience without requiring further activity from the user.

You can overwrite user dimension values by uploading new ones or by collecting new ones via your measurement code.

Deleting a user data source from the data-upload service does not delete the values stored in the user dimensions for the affected users. 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 Data Import.

Data-source details


  • Scope: the scope determines which events will be associated with the import-dimension values. Custom dimensions can have one of 3 scopes:
    • Event: Descriptive information about the event (e.g., event name)
    • User: Descriptive information about the user who triggered the event (e.g., loyalty tier)
    • Item: Description information about the information you collect in the items array within an ecommerce event
  • 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. In Admin, under Data collection and modification, click Data streams.
  2. 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