Custom event data import allows you to import data that you’ve collected outside of Google Analytics 4 (GA4) by using a combination of standard fields and event-scoped custom dimensions as join keys. You can then create custom reports for a more complete view of your Analytics data and imported event metadata.
How custom event data import works
Custom event data import allows you to import and join data in ways that make sense to you. The basic concepts, steps, and limitations of custom event data import are the same as those for other import types; however, you have more flexibility in the choice of key and import dimensions.
Start by thinking about what reporting you want to add in your reports and explorations. If this information isn't already collected by Analytics and it's not handled by one of the other data import types, you can use the Custom event data type to join this information with your Analytics data. You can then create custom reports to view the imported data alongside standard Analytics data.
Before you begin
You must be an Editor (or above) at the property level to import custom event data.
Custom event data requires you to set up event-scoped custom dimensions in your Google Analytics 4 property. Make sure to create these custom dimensions carefully before you begin to import your custom event data.
Analyze and take action
How you see your imported data in reports, and how you act upon that data with segments and other Analytics tools, will depend upon the dimensions involved. Create a file that has the additional insights you’d like to add to your reports and analysis.
Upload the data
The general upload procedure is outlined in About Data Import.
When you create the data source, select Custom event data as data type.
After you select the option to upload data from a CSV file or SFTP server, you must map the fields you imported to fields in Google Analytics. When you map fields, you'll see the following screen:
In the Key fields table:
- Click Add fields to add fields in Google Analytics to which you would like to join your imported data. This is also called the schema key.
- In the Analytics field column, you’ll see the name of the selected Google Analytics field.
- In the Analytics event parameter column, you’ll see the associated Analytics event parameter for the Analytics field.
- Note for standard fields selected, the Analytics event parameter will be set as “N/A (standard)”
In the Import fields table:
- Click Add fields to select the fields you'd like to include in your data via the selected join key. This can be across either:
- Select from standard fields and/or custom dimensions
- Type-in an event parameter that is not assigned to a custom dimension using the “+” button
- In the Analytics field column, you’ll see the name of the selected Google Analytics field.
- Note for type-in event parameter creation, the Analytics field column will be set as “N/A”. Please ensure type-in event parameters follow expected event naming conventions. Learn more about event naming rules here.
- In the Analytics event parameter column, you’ll see the associated Analytics event parameter for the Analytics field.
- Note for standard fields selected, the Analytics event parameter will be set as “N/A (standard)”
In both tables, you select the matching fields in your import file in the Import field column:
After you upload your data, it can take up to 24 hours for Analytics to make that data available in reports, audiences, and explorations.
Since custom event data import uses the reporting/query time join and does not alter data that has already been processed, you can delete a custom event data source from the data-upload service to remove custom event data from Analytics reports.
Data-source details
Legend
- Scope—the scope determines the level at which the import dimension values will be associated. There are three levels of scope for custom dimensions: user, event and item. Note that custom event data import only supports event-scoped custom dimensions.
- Key fields—also referred to as schema key, lists the key dimensions. The key is used to join the data you upload with the existing data for this Data Set type.
- Import fields—lists the dimensions and event parameters available for the data you upload to Google Analytics.
The dimensions listed here for the schema key and imported data are for reference only and may not be complete; the actual dimensions available will appear in the user interface when you create the Data Set.
| Scope | Event-scoped |
|---|---|
| Key Fields |
At least ONE and up to TWO dimensions total, made up of dimensions from categories listed below: Platform
Page / screen
Custom dimensions
If a custom dimension utilized as a key field in the data source is deleted, the import will fail. |
| Import Fields |
At least ONE and up to TEN dimensions total, made up of one or more of the dimensions from categories listed below: Page / screen
Custom dimensions
New event parameters
If a custom dimension utilized as an import field in the data source is deleted, the import will continue to work with said custom dimension no longer available in reporting. |
| Notes |
|
Limits of custom event data import
- No new events can be created with custom event data import.
- Deleting a custom dimension used in the custom data event import limitations
- If it is set as a key field, deletion will cause the custom event data import to fail.
- If it is set as an import field, deletion will not cause the custom event data import to fail. However, the deleted custom dimension will no longer be widened in reporting.
- Type-in event parameters will not be surfaced in reporting as they are not associated with a custom dimension. If a new custom dimension is created against an imported event parameter, Google Analytics replaces historical and future events with the new custom dimension in reporting.