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`](https://developers.google.com/tag-platform/gtagjs/reference#config)
  - [`get`](https://developers.google.com/tag-platform/gtagjs/reference#get)
  - [`set`](https://developers.google.com/tag-platform/gtagjs/reference#set)
  - [`event`](https://developers.google.com/tag-platform/gtagjs/reference#event)
  - [`consent`](https://developers.google.com/tag-platform/gtagjs/reference#consent)
- `<command parameters>` are the parameters you can pass to `gtag()`. Command parameters vary according to the command; refer to the [command reference](https://developers.google.com/tag-platform/gtagjs/reference#command-ref).

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](https://developers.google.com/tag-platform/gtagjs/install).

## 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 following example, 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`

> [!NOTE]
> **Note:** The `gtag('config')` command is deprecated. Use the Google Tag Manager UI to configure tag settings and destinations, or use `gtag('set')` for setting in-page parameters. **If you are using gtag.js today and use `gtag('config')` commands, you do not need to retag your website. Your setup will continue working as it does today.**
> **Why are we making this change?**
>
> Various parts of the gtag API were designed for a time when the Google tag had no UI, and all configuration had to come as in-page code. This forced you to hard-code your preferred configuration and data routing decisions directly onto your website, making it harder to change your settings later. Hard-coding also locks these settings into a specific point in the page or event lifecycle, which adds complexity and introduces the risk of race conditions.
>
> Now that the Google tag and Google Tag Manager platforms are unified, every tag now has an interface. You no longer need to make setup decisions upfront or hard-code them on your website.

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

Key points about `<TARGET_ID>`:

- The `<TARGET_ID>` in the `gtag('config', <TARGET_ID>, ...)` command
  is a Tag ID that identifies where `gtag.js` should send event data.
  This may be a destination such as a Google Analytics property, a
  Google Ads account, a Floodlight configuration, or a Google tag that has
  multiple destinations.

- A Tag ID---such as `GT-XXXXXX`, `G-XXXXXX`, or `AW-YYYYYY`---is an identifier
  for your Google tag. You add this ID to your website code to load the Google
  tag.

- A single Google tag (identified by its Tag ID) can be configured to send
  data to multiple destinations. Although some Tag IDs might look identical to
  Destination IDs, such as `G-XXXXXX` for a Google Analytics property or
  `AW-YYYYYY` for a Google Ads account, the `<TARGET_ID>` in the `config`
  command refers to the particular instance of the Google tag loaded on the
  page.

- The `gtag('config', ...)` command configures the behavior of the Google tag
  associated with that specific `<TARGET_ID>`. While the Tag ID included in
  the script `src` typically loads the Google tag, you can use any valid
  Tag ID associated with your account in the `gtag('config')` command.

- A single Google tag can have multiple Tag IDs associated with it, often due
  to tag merging. Any of these associated IDs can be used in the script `src`
  parameter to load the Google tag.

- If you are sending data to multiple destinations or using multiple tags, you
  only need to include a single Google tag snippet with one Tag ID in the
  script `src`. You then include a `gtag('config')` command for each
  additional Tag ID or destination.

`<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](https://support.google.com/tagmanager/answer/12326985) 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`

Lets you get various values from `gtag.js` including values set with the
[`set`](https://developers.google.com/tag-platform/gtagjs/reference#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](https://developers.google.com/tag-platform/gtagjs/reference#get_field_name) | 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 |
| session_number | - Google Analytics 4 |
| gclid | - Google Ads - Floodlight |

> [!NOTE]
> **Note:** If you use the [`set`](https://developers.google.com/tag-platform/gtagjs/reference#set) command with these field names, the value you set will have precedence.

### 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](https://developers.google.com/analytics/devguides/collection/ga4/reference/config#campaign)
parameters so that they can be accessed by multiple tags on the same page.

The following example 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](https://developers.google.com/tag-platform/gtagjs/reference/events). Each recommended event can take [recommended parameters](https://developers.google.com/tag-platform/gtagjs/reference/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](https://developers.google.com/analytics/devguides/collection/ga4/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'
    });

> [!IMPORTANT]
> **Important:** The Google tag snippet must appear on the same page, above `event` commands, or your data won't be sent.

## `consent`

Use the `consent` command to configure consent.

    gtag('consent', {<consent_arg>}, {<consent_params>});

See [consent](https://support.google.com/analytics/answer/9976101) 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. |