gtag.js API reference

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

gtag(<command>, <command parameters>);
  • <command> is one of the following commands:
  • <command parameters> are the parameters to be passed 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 global snippet. To learn how to add the global snippet to a page, refer to the snippet guidance.


Allows you to add additional configuration information to targets. This is typically product-specific configuration for a product such as Google Ads or 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', 'AW-CONVERSION_ID');

Similarly, the config command may be used with Google Analytics:

gtag('config', 'GA_MEASUREMENT_ID');

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', 'GA_MEASUREMENT_ID', {
  'send_page_view': false,
  'groups': 'agency'


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.


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
  • Google Analytics 4
  • Google Analytics Universal Analytics
  • Google Analytics 4
  • Google Ads
  • Floodlight


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.


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


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


Use the event command to send event data.

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

<event_name> is either:

<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'

Parameter scope

Parameters values can be scoped to an individual event, 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'

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