Google tag API reference

Page Summary

• The Google tag (gtag.js) API uses the gtag() function to send data to Google products like Google Analytics and Google Ads.

• The gtag() function uses commands like config, get, set, event, and consent to manage data and user consent.

• Parameter values can have different scopes: event, config, and set, with event having the highest precedence.

• The config command is used to configure targets like Google Analytics properties or Google Ads accounts.

• The event command sends event data, including recommended and custom events with associated parameters.

The Google tag (gtag.js) API consists of a single function, gtag(), with the following syntax:

gtag(<command>, <command parameters>);

• <command> is one of the following commands:
  • config
  • get
  • set
  • event
  • consent
• <command parameters> are the parameters you can pass to gtag(). Command parameters vary according to the command; refer to the command reference.

You can invoke gtag() commands anywhere on your page, as long as your commands appear below the Google tag snippet. To learn how to add the snippet to a page, see the installation guide.

Parameter scope

You can scope parameters values to individual events, all events sent to a specific <TARGET_ID>, or globally to all events. This is achieved by using the event, config, and set commands.

Parameter values set in one scope don't modify the values set for the same parameter in a different scope. In the following example, the config command does not modify the global value for campaign_id previously assigned with the set command. After both commands are executed, the global value of campaign_id is still '1234'.

// Set global campaign ID
gtag('set', { 'campaign_id': '1234' });

// Set campaign ID for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'campaign_id': 'ABCD' });

Parameter precedence

If different values are assigned to the same parameter in different scopes, only a single value is used when processing events. Parameter values scoped to event will take precedence over parameters scoped to config, and config parameters take precedence over parameters that are globally scoped using set.

// Set campaign information at the global scope
gtag('set', { 'campaign_name': 'Black Friday Sale' });

// Set currency for <TARGET_ID1> to 'USD'
gtag('config','<TARGET_ID1>', { 'currency': 'USD' });

// Process a conversion event with currency: 'GBP'
gtag('event','conversion', { 'currency': 'GBP', 'send_to': '<TARGET_ID1>' });

// Process a conversion event with currency: 'EUR'
gtag('event','conversion');

// Process a conversion event with currency: 'USD'
gtag('event','conversion', { 'send_to': '<TARGET_ID1>' });

config

Lets you add additional configuration information to targets. This is typically a product-specific configuration for a product, but you only need to configure this once if you're using both Google Ads and Google Analytics.

gtag('config', '<TARGET_ID>', {<additional_config_info>});

Key points about <TARGET_ID>:

• The <TARGET_ID> in the gtag('config', <TARGET_ID>, ...) command is a Tag ID that identifies where gtag.js should send event data. This may be a destination such as a Google Analytics property, a Google Ads account, a Floodlight configuration, or a Google tag that has multiple destinations.

• A Tag ID—such as GT-XXXXXX, G-XXXXXX, or AW-YYYYYY—is an identifier for your Google tag. You add this ID to your website code to load the Google tag.

• A single Google tag (identified by its Tag ID) can be configured to send data to multiple destinations. Although some Tag IDs might look identical to Destination IDs, such as G-XXXXXX for a Google Analytics property or AW-YYYYYY for a Google Ads account, the <TARGET_ID> in the config command refers to the particular instance of the Google tag loaded on the page.

• The gtag('config', ...) command configures the behavior of the Google tag associated with that specific <TARGET_ID>. While the Tag ID included in the script src typically loads the Google tag, you can use any valid Tag ID associated with your account in the gtag('config') command.

• A single Google tag can have multiple Tag IDs associated with it, often due to tag merging. Any of these associated IDs can be used in the script src parameter to load the Google tag.

• If you are sending data to multiple destinations or using multiple tags, you only need to include a single Google tag snippet with one Tag ID in the script src. You then include a gtag('config') command for each additional Tag ID or destination.

<additional_config_info> is one or more parameter-value pairs.

This example configures a tag to send data to a Google Ads account:

gtag('config', 'TAG_ID');

where "TAG_ID" is the tag ID for the Google tag.

To demonstrate how to send additional config information, here is an example that configures a tag to send data to an Analytics account with a send_page_view parameter that passes a value of false, and a groups parameter that passes a value of 'agency'.

gtag('config', 'TAG_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

get

Lets you get various values from gtag.js including values set with the set command.

gtag('get', '<target>', '<field_name>', callback)

Argument	Type	Example	Description
<target>	string	G-XXXXXXXXXX	The target to fetch values from.
<field_name>	FieldName	client_id	The name of the field to get.
callback	Function	(field) => console.log(field)	A function that will be invoked with the requested field, or undefined if it is unset.

FieldName

Field name can be the name of a custom field you set with the gtag('set') command, or one of the following values:

Field Name	Supported Targets
client_id	Google Analytics 4
session_id	Google Analytics 4
session_number	Google Analytics 4
gclid	Google Ads Floodlight

Note: If you use the set command with these field names, the value you set will have precedence.

Examples

Get value into a Promise

const gclidPromise = new Promise(resolve => {
  gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});

gclidPromise.then((gclid) => {
  // Do something with gclid...
})

Send event to the Measurement Protocol

gtag('get', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

function sendOfflineEvent(clientID, eventName, eventData) {
  // Send necessary data to your server...
}

Get a value you set

gtag('set', {campaign_name: 'Spring_Sale'});

gtag('get', 'G-XXXXXXXXXX', 'campaign_name', (campaign_name) => {
  // Do something with currency value you set earlier.
})

set

The set command lets you define parameters that will be associated with every subsequent event on the page.

Note: We recommend using config or event commands wherever possible.

gtag('set', {<parameter-value-pair>, <parameter-value-pair>});

For example, you can share campaign parameters so that they can be accessed by multiple tags on the same page.

The following example illustrates setting a campaign name and ID for a Black Friday shopping event. Because you've used set, all other tags, for example, GA4 Event tags or Google Ads Remarketing tags, can access this data.

gtag('set', 'campaign', {
  'id': 'abc',
  'source': 'google',
  'name': 'black_friday_promotion',
  'term': 'running+shoes',
});

event

Use the event command to send event data.

gtag('event', '<event_name>', {<event_params>});

<event_name> is either:

• A recommended event. Each recommended event can take recommended parameters.
• A custom event. A custom event is an arbitrary event name that you make up, with arbitrary parameters. For more information, see Set up events.

<event_params> is one or more parameter-value pairs. Each pair separated by a comma.

The following event command fires the recommended event screen_view with two parameters: app_name and screen_name.

gtag('event', 'screen_view', {
  'app_name': 'myAppName',
  'screen_name': 'Home'
});

Important: The Google tag snippet must appear on the same page, above event commands, or your data won't be sent.

consent

Use the consent command to configure consent.

gtag('consent', {<consent_arg>}, {<consent_params>});

See consent in the help center for more information on the behavior these parameters configure.

<consent_arg> is one of 'default' or 'update'. 'default' is used to set the default consent parameters that should be used, and 'update' is used to update these parameters once a user indicates their consent.

The following <consent_params> are supported:

Field Name	Allowed Values	Description
ad_storage	'granted' | 'denied'	Enables storage, such as cookies (web) or device identifiers (apps), related to advertising.
ad_user_data	'granted' | 'denied'	Sets consent for sending user data to Google for advertising purposes.
ad_personalization	'granted' | 'denied'	Sets consent for personalized advertising.
analytics_storage	'granted' | 'denied'	Enables storage, such as cookies (web) or app identifiers (apps), related to analytics, e.g. visit duration.
wait_for_update	any positive integer	Sets a time in milliseconds to wait for a consent update call.