Google tag API reference

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, below.

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.

`config`

Allows you to 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>});

<TARGET_ID> is an identifier that uniquely identifies the target for hits, such as a Google Analytics property or a Google Ads account. <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`

Allows you to 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`	UA-XXXXXXXX-Y	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 Google Analytics Universal Analytics
session_id	Google Analytics 4
gclid	Google Ads Floodlight

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', 'UA-XXXXXXXX-Y', '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', {currency: 'USD'});

gtag('get', 'UA-XXXXXXXX-Y', 'currency', (currency) => {
  // Do something with currency value you set earlier.
})

`set`

Allows you to set values that persist across all the subsequent gtag() calls on the page.

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

<parameter-value-pair> is a key name and the value that is to persist across gtag() calls. For example, the code below sets the value of country to 'US' and the value of currency to 'USD' for all subsequent events on the page:

gtag('set', {
  'country': 'US',
  'currency': 'USD'
});

Using the set command differs from passing values directly to the event command. When you pass values directly to an event command, those values only apply to the event being fired. But with set, the values persist on the current page and are passed with all subsequent events. To illustrate, contrast the following two examples:

gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');

and

gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');

In the first example, the login event will be passed with a method value of 'Google' and the share event will be passed without any parameters. In the second example, both login and share will be passed with a method value of 'Google'.

`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 (i.e. custom) parameters. For example, see how custom events are used in Google Analytics.

<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'
});

`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
`ad_storage`	`'granted'` \| `'denied'`
`analytics_storage`	`'granted'` \| `'denied'`
`wait_for_update`	any positive integer

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 do not modify the values set for the same parameter in a different scope. In the example below, the config command does not modify the global value for currency previously assigned with the set command. After both commands are executed, the global value of currency is still 'EUR'.

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

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

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 global currency to Euros
gtag('set', { 'currency': 'EUR' });

// 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>' });