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:<command parameters>
are the parameters you can pass togtag()
. 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
|
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 |
|
session_id |
|
gclid |
|
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 (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 | 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. |