Configuration

Configure the gtag extension with your Google products, as well as advanced gtag.js settings.

This extension allows you to setup multiple accounts for multiple product types, from one interface. You can have an unlimited number (though we'd feel bad for your visitors having to load 1000's of conversion pixels...) of Google Analytics, Google Marketing Cloud (DoubleClick Floodlight), and Google Ads (AdWords) accounts setup within this extension.

To get started, click the "Add Account" button and fill in the fields. Descriptions of the fields and their importance can be found below.

New installations will see this message. Click the "Add Account" button to get started.

Accounts

Each account is configured independently and a description of the fields shown in the extension configuration can be found below.

Account Info Settings

Below are all of the settings that are available for accounts.

Account Name

The name is only used to reference this account in the various settings in Launch. It can be anything, but it is recommended to be descriptive.

Account ID

This should be the account ID provided from the Google product's interface. It can also be a data element that returns this account ID. If a data element is not used, the account ID should start with AW-, DC-, or UA-. Once a product is added, you can add additional account IDs for each Launch environment. It is recommended to send data in the development or staging environments to a different account ID to keep the data within the Google product clean of test/QA data.

Note: If an account ID is not provided for the development or staging environments, the production account ID will be used as a fallback.

Product Type

The product type that this account belongs to. If you've entered an account ID string, as mentioned above, this will be pre-populated for you and cannot be changed.

Warning: You cannot change the product type once the account has been added. If you're using a data element be sure to select the correct product type.

Product-Specific Account Settings

Google Analytics
Google Ads
Google Marketing Cloud

Cookies & User IDs

You can change the various settings around the cookies, as well as pass a user ID here. Learn more.

The name of the cookie that is set by Google Analytics. Defaults cookie_name to _ga

The domain that the Google Analytics cookie should be set to. Defaults cookie_domain to auto. You should only use this to limit the cookie to a subdomain.

The number of days the cookie should remain uneaten in the user's browser. The default value for cookie_expires is 730.

User ID

A user ID that is unique, persistent, and non-personally identifiable can be sent to Google Analytics to help identify users across devices via user_id. Be sure to have a user ID view enabled on the property.

Cross Domain Tracking

Google Analytics can track users across domains by passing a _ga URL parameter in links on the page to other domains with the visitor's Google Analytics ID and an expiration timestamp. Learn more about cross domain tracking.

Accept Incoming

If this setting is enabled, any visits to the page that contain the _ga parameter will have it parsed and the visitor's ID will be set for the current domain. If you only have a single domain, you can disable this without any loss of traffic. If you have multiple domains you want to track visitors across, this should be enabled. If any domains are entered in the "Domains" field, this will automatically be enabled and cannot be disabled. If a data element is used, it should return a boolean true/false.

Decorate Forms

By default, forms that are submitted to other domains will not have the _ga parameter added to the URL. If this setting is enabled, those forms will decorate the URL with the _ga parameter upon form submission. If a data element is used, it should return a boolean true/false.

Custom Dimensions & Metrics

In Google Analytics, you can set custom dimensions and metrics that can enrich the out-of-the box data to help with your business' reporting needs. With gtag, you must first map your custom dimensions to custom fields since multiple Google products share the same custom fields. This means that if you are setting an "Account Type" into the custom fieldaccount_type, it can then be used within Google Marketing Cloud and Google Ads. You can learn more about setting custom dimensions for Google Analytics via gtag in Google's documentation.

The mapping consists of two parts:

  1. Custom Dimension / Metric Name - this should be the dimension or metric name from the Google Analytics interface, such as dimension1 or metric52.

  2. Data Field Name - this should match the name you use in the Custom Data Fields section. If you do not have a field already in mind / mapped, you should create a name the is unique and descriptive. The name should be alphanumeric and may include underscores.

Using account type as an example, if you have a custom dimension setup in Google Analytics with an index of 1:

Account Type setup in Google Analytics as Custom Dimension 1

Then your mapping should look similar to this:

dimension1 is now mapped to the account_type custom data field

Then, in the custom data fields section (in the extension configuration or any of the actions), you can pass in static values or data elements as values to your dimension/metric.

Custom Data Field that maps the account_type data element to account_type (dimension1)

Data will then flow from the account_type data element into dimension1 on actions that are mapped. Learn more on when to map custom data fields.

After a custom dimension or metric is mapped, the data field name will show up in the autocomplete boxes within custom data fields input.

The "account_type" field is populated in the autocomplete dropdown.

Note: Safari users will not see the autocomplete since Safari does not yet support data lists.

Privacy Settings

IP Anonymization

If this setting is enabled, visitor's IP address will be anonymized by removing the last octet. Learn more on how Google processes data with this setting.

General Settings

Below are the available settings for Google Ads.

Conversion Linker

When enabled, this allows you to track incoming visitors via the _gcl_aw first party cookie. This allows visitors to be tracked to the conversion event. It is recommended to enable this, but if you need to prevent first party cookies from being set by Google Ads, you should disable this feature.

By default, all accounts will use the same cookie name. If you've added multiple Google Ads accounts, it is generally recommended to set a prefix to the cookie to keep the conversions separated. Learn more in Google's documentation.

There are currently no Google Marketing Cloud specific settings. Any settings that Google adds in the future can be set via the Custom Data Fields below until Acronym has updated the extension to include the latest settings.

Custom Data Fields

Custom data fields in the gtag extension allow you to map any additional settings that weren't listed above, as well as setting custom dimension and metric values. For Google Analytics, seeing above for mapping custom dimension and metrics.

You can set these custom data fields in for all of the gtag extension's actions, each with their own use case of why you'd use it there.

Note: If you've passed a data element into either the field or the value, it will be re-evaluated each time an action is executed. This means if your data element is referencing a JS variable and that variable's value has changed, the new value will be sent with the action.

Extension Configuration

Passing custom data fields within the extension configuration will set that value on every page view, but will not set it for any events. This should be used for additional configuration settings that are not shown in the extension UI.

Set persistent values

Setting custom data fields in the set persistent values action will persist the value on every page view or event made after this action. This is useful for setting information about the user that should be included on every hit and doesn't change. The account type example mentioned in the Google Analytics settings above would be a great use case for the set persistent values action.

Send a page view

When setting custom data fields in the send a page view action, the values will only be sent with that page view. A use case of this would be to overwrite the page_title or page_path values if you want to change the page's title that you would see in the reports.

Send an event

Finally, you can set custom data fields within the send an event action. Like the send a page view action, custom data fields set within the send an event action will only be passed on that single event. This is useful for passing more information about the event (e.g. login method).

Data Persistence

It is important to note how Google persists data when using these fields. Custom data fields set in events will have priority, followed by the page views, followed by the set persistent values action.

Let's say you had the following actions called for your accounts:

Action

Data Field in the Action

Value captured by Google

Set persistent values

page_title = "my page"

(no data captured here)

Page view

(nothing)

"my page"

Event

page_title = "another page"

"another page

Pretty straight forward, right? Now let's look at another, more complex example:

Action

Data Field in the Action

Value captured by Google

Set persistent values

page_title = "my page"

(no data captured here)

Page view

page_title = "example title"

"example title"

Event

(nothing)

"example title"

Page View

(nothing)

"example title"

Event

page_title = "another page"

"another page"

Page View

(nothing)

"example title"

Finally, let's look at one last example, where the extension configuration has a custom data field:

Action

Data Field in the Action

Value captured by Google

Extension Configuration

page_title = "original page"

(no data captured here)

Set persistent values

page_title = "my page"

(no data captured here)

Page view

(nothing)

"original page"

Event

page_title = "another page"

"another page"

Page view

(nothing)

"original page"

You can see how this can get confusing when you're trying to persist custom data fields. The set persistent values action is useful for setting values that won't change and apply to all accounts. Otherwise, you're better off setting the value in the config.You can read more about this in Google's documentation.

Removing / Disabling Accounts

Since this extension allows you to add multiple accounts, at some point you may need to remove or disable an account.

Disabling Accounts

Right now, it is not possible to disable an account from the extension configuration. This is because Adobe bundles all settings saved into the library on the page. We've opted to keep the Launch library as light as possible for your end users and not include any settings for accounts that would be disabled. We're looking into potential workarounds, but please vote on our idea to allow for this natively in Launch.

For the time being, it is recommended that you disable the account in each of the rule actions, which will prevent the data from being sent to that account.

Removing Accounts

To remove an account from the extension, navigate to the account and then click the "Remove Account" button at the bottom of the account's settings. A confirmation will appear to make sure you want to remove the account.

The warning popup when you attempt to remove an account.

It is then recommend go into any rule actions that used the account, and save the changes to remove any additional bloat (the account settings if it was enabled for that rule) within the Launch library. Unfortunately, the Launch API for extensions does not allow for developers to automatically update other action settings, so this must be a manual process. We have an idea in the Adobe forums to allow extension developers to automate this, so please vote to see this implemented!

Warning: You cannot re-create the account by entering the same account name/ID. You must rollback your configuration to the previous version. This is because the backend IDs are generated upon initial creation and will change when you re-add the account. If you did add a new account you'd need to re-set up all of the rules / actions for the account.

If you've removed an account, you can still re-add the account by comparing versions (the ... button at the top right of the extension configuration screen), selecting the previous revision, and clicking the "Use these changes" button.

Revision comparison showing an account that was removed in the latest version

If you've saved any rules that used the deleted account since it was deleted, you'll need to rollback the rule to the previous version as well.

Advanced Settings

These settings are completely optional and geared towards more advanced users. If you're unsure of a setting, you should leave it blank to keep the default.

Data Layer Name

The data layer name is the name of the JavaScript variable that is set in the window scope for gtag to store the data. This should not be your existing data layer name or be the name of any existing variables on the page (unless you're OK with potentially overwriting it). By default this is set to dataLayer, but Acronym recommends that this should be changed to something else as dataLayer is a relatively common JavaScript name used in marketing tools. Examples of unique data layer names that could be used: gtagDataLayer, companyNameDataLayer , or gtagData. The value passed should be a valid JavaScript variable name and should not be a reserved keyword. Do note that we do not allow Unicode letters at this time (sorry, is currently not an acceptable name!)

Function Name

The function name is the name of the JavaScript function that is set in the window scope that is called for each event. By default it is set to gtag. It is not recommended to change this unless you have an existing variable named gtag conflicting on your site. The name of this should be a valid JavaScript variable name and should not be a reserved keyword. Do note that we do not allow Unicode letters at this time.

Custom Configuration Code

You can execute JavaScript using this setting. Your code will execute after the gtag() function,dataLayer variable, and accounts are all initialized. No page view, event, or set commands have happened at this point, but all of the accounts are available. Your custom code will have access to the gtag function and the dataLayer array. Any returned value will be ignored.

An example of the custom code setting, you could inspect the gtag and dataLayer arguments:

console.log(gtag, dataLayer);

Display Features

By default, Google has enabled display features, or data collection for personalized ads. This setting lets you turn display features off for everyone, or conditionally by providing a data element. Your data element should return a boolean true or false.

Note: Additional settings in the Google product interfaces may need to be enabled for you to collect the demographic data. Learn more about display features in Google Analytics and DoubleClick