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.

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 example below, 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`

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`	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
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', '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.

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

`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.