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.
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:
- Using the User ID dimension
Learn how to set a user ID - Using a custom dimension with the scope set to user and with a user property to capture the user identifier
Learn more about best practices to avoid sending PII to 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
Legend
- 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:
|
| Imported data |
User properties |
| Notes |
You may not upload or associate personally identifiable information with user-data import. Learn more |
Templates
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 |
User-ID
| 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
- In Admin, under Data collection and modification, click Data streams.
- Open the relevant data stream.
The Stream ID is located on the left side of the details header.
