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 three gtag commands: config, set, or event.
  • <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.

config

Allows you to add additional configuration information to targets. This is typically product-specific configuration such as Google Analytics tracking information.

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 an AdWords account. <additional_config_info> is one or more parameter-value pairs.

This example configures a tag to send data to an AdWords account:

gtag('config', 'AW-CONVERSION_ID');

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

gtag('config', 'GA-TRACKING_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-TRACKING_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

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:

<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'
gtag('event','conversion');

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