[GA4] Import custom event data

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

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.

Note: Custom event data import only supports event-scoped custom dimensions. Learn more about setting up custom dimensions.

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

  • Stream ID

Page / screen

  • Hostname
  • Page path
  • Pate title
  • Page title and screen class
  • Page title and screen name

Custom dimensions

  • Custom dimension (event scoped)

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

  • Hostname
  • Page path
  • Pate title
  • Page title and screen class
  • Page title and screen name

Custom dimensions

  • Custom dimension (event scoped)

New event parameters

  • Typed in 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
  • All selected dimensions must be unique across key fields and import fields.
  • You can only have one data source when you import custom event data.
  • Typed in event parameters must follow expected event naming conventions. Learn more about event naming rules here.

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.

Related resources

Was this helpful?

How can we improve it?
Search
Clear search
Close search
Google apps
Main menu