[GA4] Understand data sources

A data source is a container that holds the data you upload to Analytics, and comprises the database, service, or CSV file you upload and a mapping of Analytics fields to the fields in your external database, service, or CSV. Data sources control how uploaded data gets joined with existing data. You configure data sources at the property level.

To manage the data sources for a property, click Admin, then under Data collection and modification, click Data import.

Data-source types

A data-source type corresponds to the specific type of data you want to import. For example, there are data-source types for:

• cost data
• item data
• user data
• offline-event data

For each one, you have different options for the dimensions and metrics (the schema) you can upload data for. Depending on the data source, you can choose to:

• Upload a CSV
• Use SFTP
• Connect to Salesforce (Learn more).

Import offline Salesforce data

This section is for users who wish to import offline Salesforce event data in Google Analytics 4. Salesforce import uses the offline-event data import type. Learn more how to Import offline-event data.

Note:

• You must have the Editor role for the Analytics property you'll use for importing the data.
• The code samples in this section are provided as reference. Your specific implementation details may require additional code or different approaches.

Step 1: Decide how to identify your users

Analytics offers 2 ways to programmatically identify your users: Client ID and User-ID. To support Data Import for Salesforce, you must implement Client ID. You may optionally choose to also implement User-ID.

Client ID pseudonymously identifies a browser instance. This is a non-authenticated, cookie-based identifier created automatically by an Analytics-enabled site on a user’s first visit.

User-ID enables the analysis of groups of sessions, across devices, using a unique, persistent, and non-personally identifiable ID string representing a user.

You must add the Client ID, and optionally your User ID, to your lead form page and any other pages you want to measure. You can do this via Google Tag Manager or a JavaScript variable.

Note: Use of the User-ID feature is subject to the Measurement Protocol / SDK / User-ID Policy.

Step 2: Configure access for Salesforce objects and fields

To set up the Analytics Salesforce integration, you must have full access to the following Salesforce objects and fields. A Salesforce user account with System Administrator access may already have access to these fields.

In addition, be sure to grant Modify All Data permission to the user who is linking your Salesforce and Analytics accounts. This is required by the Salesforce Metadata API to enable Google to fetch Lead conversion settings data. This integration does not modify your Salesforce account and the Metadata API is used in a read-only capacity.

Note: User accounts with limited access to leads or opportunities may not have sufficient access to the data you want to import. For example, a Sales Representative account may only be able to see data for limited geographies or opportunities, and so should not be used to link Analytics and Salesforce. Check the following table for a list of required fields.

Show me the list of required fields

Object	Required Fields
LeadStatus	ID MasterLabel SortOrder
OpportunityStage	ID MasterLabel SortOrder IsActive
LeadHistory	CreatedDate OldValue NewValue Field
Lead	Status GACLIENTID* GAUSERID* GAMEASUREMENTID*
OpportunityFieldHistory	CreatedDate OldValue NewValue Field
Opportunity	Amount StageName GACLIENTID* GAUSERID* GAMEASUREMENTID*
OpportunityLineItem	All fields
Product2 (Products)	All fields
Pricebook2 (Price Books)	All fields

* Custom fields created in step 3 below.

If you use Salesforce Group Edition or Professional Edition, field access is granted by adding the necessary fields to your Lead and Opportunity page layouts. Learn more about setting page layouts and field-level security in Salesforce.

Step 3: Create new custom fields in Salesforce

Following these instructions create three custom fields in Salesforce to store your Analytics information. You can name your fields as you like. The following names are just recommendations, but we suggest these recommended names as they can assist in implementation as well as future debugging (if needed).

Field Name	API Name	Field Length
GACLIENTID	GACLIENTID__c	255
GAUSERID	GAUSERID__c	255
GAMEASUREMENTID	GAMEASUREMENTID__c	255

Note:

• You must implement Client ID and can optionally implement User-ID.
• Field names MUST be uppercase. Field labels can be whatever you want.
• Make these fields read-only to prevent unwanted changes.
• These fields MUST be created in both the Lead and Opportunity objects.

Step 4: Configure the Lead and Opportunity objects

For the Lead object, enable Field History Tracking for the Lead status field. For the Opportunity object, enable Field History Tracking for the Stage field. This will ensure that any update to these fields will generate an event.

Map the fields in each object to their counterpart in the other object:

• Lead.GACLIENTID to Opportunity.GACLIENTID
• Lead.GAUSERID to Opportunity.GAUSERID
• Lead.GAMEASUREMENTID to Opportunity.GAMEASUREMENTID

Step 5: Edit your lead form

Modify your lead form to capture and store the required tracking information. You'll need to know your Measurement ID. Learn more about Measurement ID.

Why is my Measurement ID required?

Including your Analytics Measurement ID allows you to distinguish data imported from multiple lead forms — across various sites tracked with different Analytics accounts — all passed to a single Salesforce account. This wouldn't be possible using only Client ID and/or User-ID.

Add the custom tracking fields

The following examples show how you might add the custom fields you created above to your lead form using JavaScript.

<form action="" name="myForm">
    Phone: <input type="text" name="phone_number">
    <input type="hidden" id="GACLIENTID" name="GACLIENTID" value="">
    <input type="hidden" id="GAUSERID" name="GAUSERID" value="">
    <input type="hidden" id="GAMEASUREMENTID" name="GAMEASUREMENTID" value="G-XXXXX">
    <input type="submit">
</form>

Note: The sample code above adds both Client ID and User-ID to your form. You can remove the GAUSERID line if you are only using Client ID. Replace G-XXXXX with your Measurement ID.

Set the custom tracking field values

Add this code to your lead form to populate the Client ID and User-ID values.

<script type="text/javascript">
    document.getElementById('FORM_ID').addEventListener(
    'submit', function(event) {
      ga(function() { 
        var tracker = ga.getAll()[0];
        var clientId = tracker.get('clientId');
        document.getElementById('GACLIENTID').value = clientId;
        var userId = tracker.get('userId'); 
        document.getElementById('GAUSERID').value = userId; 
      });
    });
</script>

Step 6: Link Analytics to your Salesforce account

Link Analytics to your Salesforce account by creating a new Data import configuration and authenticating access to your Salesforce account.

A data-source type corresponds to the specific type of data you want to import. For example, there are data-source types for cost data, item data, user data, and offline-event data. For each one, you have different options for the dimensions and metrics (the schema) you can upload data for. Salesforce import uses the offline-event data import type. Learn more about importing offline-event data.

Import Salesforce data

To import offline Salesforce data on Leads and Opportunities using Data Import, complete the following steps:

1. Click Admin, then under Data collection and modification, click Data import.
2. Click Create data source.
3. Enter a name for your data source.
4. Select Offline events data as the data type.
5. Click Review terms if prompted and accept the User Data Collection Acknowledgement. This is a prerequisite for uploading offline events and/or user data.
6. Under Upload data for import select Salesforce as the Import source.
7. Authenticate with Salesforce in the popup window that appears.
8. Select the Import schedule. Note that standard properties support daily import while Analytics 360 customers can select hourly.
9. Click Next.
10. Choose the Salesforce milestones and fields you want to measure as Analytics events. See Step 7, Step 8, and Step 9, below.
11. Click Import. After the initial import the data will be imported as scheduled.

Step 7: Set up your leads

Select keys, milestones, and optional fields for the leads you wish to collect as events.

Step 8: Set up your opportunities

Select keys, milestones, and optional fields for the opportunities you wish to collect as events.

If you would like Opportunity conversion events to effect the revenue and LTV (Lifetime Value) stats, we advise you to map the following:

• Map the final conversion milestone (the opportunity won milestone) to the ‘purchase’ event. This enables revenue to accrue appropriately for those events which may contain revenue.
• Map ‘amount’ (this holds the revenue amount for the winning opportunity) to the ‘value’ parameter (the parameter for which GA4 collects revenue data).
• Finally, you can map ‘Id’ (or another field representing the transaction id more appropriately) to the GA4 ‘transaction id’ field.

Standard supported fields

You can import attributes from the following standard Salesforce Lead fields:

• Id
• Industry
• NumberOfEmployees
• Rating
• ScoreIntelligenceId (if available in your Salesforce Edition)

You can also import the following standard Opportunity fields:

• Amount
• CampaignId
• ContractId
• ExpectedRevenue
• Id
• LeadSource
• Name
• Probability
• TotalOpportunityQuantity

Supported formats

In addition to the standard fields listed above, you can import all custom attribute fields with the following Salesforce field formats:

• boolean
• currency
• date
• datetime
• dateTime (camelCase)
• double
• int
• percent
• picklist
• string
• textarea
• time

To import attributes:

1. Select the Analytics custom dimensions and/or custom metrics that you want to contain the attribute data.
2. Make sure that the selected custom dimensions have the correct scope. In most cases, this will be user properties. Learn how to Understand GA4 scopes.
3. Use the drop-down menu in the Salesforce field name column to map the Analytics fields to your Salesforce fields.

If the selected Salesforce field already includes some data, you can click Preview values to make sure that data looks right. This allows you to check the accuracy of your configuration.

Example configuration

Here is an example of a supported standard Salesforce fields and Analytics custom fields mapping.

Analytics custom field: scope	Salesforce field name
Dimension: event OR user	Lead: Lead ID
Dimension: event OR user	Lead: Lead Score (Salesforce Einstein predicted score)
Dimension: user	Lead: Industry
Dimension: event OR user	Lead: Rating
Dimension: event OR user	Opportunity: Opportunity ID
Metric: event	Opportunity: Amount
Dimension: event OR user	Opportunity: Probability (%)
Metric: event	Opportunity: Expected Amount
Dimension: event OR user	Opportunity: Order Number

Which scope should I use?

Whether you use event or user scope for your custom dimensions depends on your use case. For example, if you sell multiple types of products, and are gathering multiple lead forms per user, an event- scoped custom dimension works better than a user-scoped dimension, because a user-scoped dimension will be overwritten by subsequent leads for that user.

 

You should apply this same consideration to all of the Salesforce fields listed in the example above, as well as any other custom fields you wish to import.

Step 9: Test your setup

Test your configuration by checking if your imported Salesforce data is visible in your Analytics reports (for example, the Events report or the Realtime report) and Explorations.

To check the status of your most recent import go to Admin, then under Data collection and modification, click Data import.

Notes and limits

• Make sure you abide by the Analytics Terms of Service and Privacy Policy.
• Don't import personally identifiable information (PII).
• Imported data uses the currency (or currencies, if you have multi-currency enabled) set up in your Salesforce account.
• Salesforce item data is imported to the Opportunity object, not Lead data.
• Empty fields are removed at the time of import.
• Item data is limited to 200 unique item indexes.

Data-source schema

When you create a source, you define a schema, the structure that joins the data you upload with the existing Analytics event data. A simple schema consists of a join-key dimension (the "key") and the import dimension(s) or metric(s). To import data, Analytics looks for key values in event data that match key values in the uploaded data. When Analytics finds a match, it adds (or replaces if data was already collected) the additional dimension and metric values associated with that key to the existing event data. Some data-source types let you use multiple dimensions to define the key, and most can use multiple dimensions/metrics for the import fields.

The join key is composed of at least one Analytics dimension, and can be composed of up to three.

The key dimensions vary based on the type of data set you choose.

A list of available key dimensions is provided in the drop-down menu in the data-source schema builder.

You can upload data via the same data source multiple times as long as you are just adding values to existing fields. If you want to add fields to a data source, you need to delete the existing data source and then create a new one -- once you save a data source, you can't change the mapping of Analytics fields to the fields in your CSV.